ImageGear .NET v25.1 - Updated
ImageGear.Web Back-End API
User Guide > How to Work with... > Common Operations > Viewing > Viewing with the HTML5 Viewer > ImageGear.Web Back-End API

The ImageGear.Web back-end service is bound via configuration settings in Web.config and accessed via "ImageGearService.svc".

Extending the Back-End API

The back-end API can be modified and extended by using custom data provider implementations. This flexibility allows for the implementation of many different types of use cases.

An example of extending the ImageGear.Web back-end can be found in the HTML5 Viewer. In the provided sample, the back-end has been extended by implementing Viewing Sessions with a simple use case allowing the selection of a markup layer to be loaded with a given document.

This is accomplished by adding additional Data Providers classes, adding a ViewingSession model, and creating a corresponding controller. Configure the Web.config file to add the ViewingSessionProvider with the functionality, which then becomes available in the HTML5 Viewer through the createViewerFromViewingSession() JavaScript function.

See the provided code snippets in the following files for more information on how this feature is implemented:

Providers:

Models:

Controllers:

Sample Implementation:

Data Providers and Document Identifiers

ImageGear.Web supports the use of multiple simultaneous data providers, configurable through Web.config and/or the Web.Config Editor. A single data provider must be specified as a default. This is the data provider to which requests will be sent if not explicitly directed to a particular data provider.

The document identifier takes the following generic form:

DocumentID = [e|u]{dataProviderIdentifier}{parseToken}{streamIdentifier}

Viewing API - Overview of REST API Endpoints

Uploading

Document and Page Information

Page Conversion and Rasterization

Viewing API

The ImageGear.Web back-end is a REST API which provides for the retrieval of document information, image processing and conversion operations. This API facilitates the display of document formats that are not able to render natively in the browser. These document formats are converted to a rendered format of either SVG, PNG, or JPEG format for in-browser display.

For raster render formats (PNG, JPEG), the back-end also facilitates scaling and/or cropping of the rasterized document. Such functionality may be used to generate thumbnails.

The ImageGear.Web back-end also provides the capability of handling document uploads which may be directed to a particular data provider.

Uploading 

Description

Uploads a document to document to a Data Provider and returns the id with which it is stored on the server.

Endpoint

POST .../ImageGearService.svc/Document

Query String Parameters

provider

Optional. The name of the Data Provider that will be used to store the document.

encoding

Optional. The manner of encoding of the transmitted data. Must be either "base64" or "binary". Defaults to "base64".

Returns

A raw string representing the identifier with which the document was stored on the requested provider, or 400 or 500 upon error.

Example

Request

POST .../ImageGearService.svc/Document?provider=FileImageDataProvider&encoding=binary

Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream

beb3d860-4878-41d3-b59a-352ee40e8377

Document and Page Information

Document Information

Description

Retrieves information about a particular document

Endpoint

GET .../ImageGearService.svc/Document/q/Attributes

Query String Parameters

DocumentID

Required. The Document ID of the requested document.

provider

Optional. The provider to which to direct the request. Can also be specified as part of DocumentID.

Response

A JSON object containing the following properties, or a 404 or 500 upon error.

Property

Type

Description

contentType

string

The MIME type of the source document.

formatId

number

The ImageGear.Formats.ImGearFormats enum value of the source document

format

string

The format name of the source document. (ex. "JFIF")

formatDescription

string

The full format name of the source document (ex. "JPEG File Interchange Format")

pageCount

number

The page count of the source document.

pageCountConfidence

number

Currently always 100. Possibly subject to change.

isRaster

boolean

Whether the source document is of a raster format.

isVector

boolean

Whether the source document is of a vector format.

isSvgCompliant

boolean

Whether the source document is able to be rendered as SVG. (Untrue of source document in raster format).

Example

Request

GET
ImageGearService.svc/Document/q/Attributes?DocumentID=umyfile.pdf 

GET

ImageGearService.svc/Document/q/Attributes?DocumentID=udataProviderName!myfile.pdf 

GET

ImageGearService.svc/Document/q/Attributes?DocumentID=umyfile.pdf&provider=dataProviderName

Response

HTTP/1.1 200 OK
Content-Type application/json

{
   "contentType": "application/pdf",
   "format": "PDF",
   "formatDescription": "Adobe PDF",
   "formatId": 13,
   "isRaster": false,
   "isSvgCompliant": true,
   "isVector": true,
   "pageCount": 108,
   "pageCountConfidence": 100
}

Page Information

Description

Retrieves information about a specific page in a document

Endpoint

GET .../ImageGearService.svc/Page/q/{pageNumber}/Attributes

URL Parameters

pageNumber

Required. The index of the page whose attributes are requested starting from 0.

Query String Parameters

DocumentID

Required. The Document ID of the requested document.

provider

Optional. The provider to which to direct the request. Can also be specified as part of DocumentID.

Response

A JSON object containing the following properties, or a 404 or 500 upon error.

Property

Type

contentType

string

A comma-separated list of all the supported output formats to which the source document can be rendered. May include "jpeg", "png", and/or "svg".

fileImageCount

number

Always returns 1.

imageBitDepth

number

The bit depth of the source document.

imageHeight

number

The height in pixels of the source document.

imageWidth

number

The width in pixels of the source document.

imageXResolution

number

The horizontal resolution in DPI of the source document.

imageYResolution

number

The vertical resolution in DPI of the source document.

isRaster

boolean

Whether or not the source document is in of a raster format.

pageCount

number

The page count of the source document.

Examples

Request

GET
ImageGearService.svc/Document/q/0/Attributes?DocumentID=umyfile.pdf 

GET

ImageGearService.svc/Document/q/0/Attributes?DocumentID=udataProviderName!myfile.pdf 

GET

ImageGearService.svc/Document/q/0/Attributes?DocumentID=umyfile.pdf&provider=dataProviderName

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "contentType": "jpeg,png,svg",
   "fileImageCount": 1,
   "imageBitDepth": 24,
   "imageHeight": 842,
   "imageWidth": 595,
   "imageXResolution": 72,
   "imageYResolution": 72,
   "isRaster": false,
   "pageCount": 108
}

Page Conversion and Rasterization

Full Page

Description

Retrieve a full page from a document rendered as SVG, PNG, or JPEG.

Endpoint

GET .../ImageGearService.svc/Page/q/{pageNumber}

URL Parameters

pageNumber

Required. Page number starting from 0.

Query String Parameters

DocumentID

Required. The Document ID of the requested document.

provider

Optional. The provider to which to direct the request. Can also be specified as part of DocumentID.

contentType

Optional. The content type to which to render the source document. Must be one of either be "svg", "png", or "jpeg". Defaults to "jpeg".

scale

Optional. Defaults to 1.0. Only valid for PNG or JPEG render formats. Will fail or generate an error if specified as a value other that 0.0 or 1.0 and the render type is SVG.

quality

Optional. Values range from 1-99. Defaults to 85. Only applicable for JPEG render format. A value of 100 implies PNG output.

Response

A web-compatible representation of the requested document and page number or 404 or 500 upon error.

Examples

Request

GET .../ImageGearService.svc/Page/q/0?DocumentID=umyProviderName!myFile.pdf&contentType=jpeg&scale=.5

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg 

<<jpeg image data>>

Request

GET .../ImageGearService.svc/Page/q/0?DocumentID=umyfile.pdf&provider=myProviderName&contentType=svg

Response

HTTP/1.1 200 OK
Content-Type: image/svg+xml

<<svg image data>>

Page Thumbnail

Description

Returns a thumbnail image for the requested document and page number

Endpoint

GET .../ImageGearService.svc/Page/q/{pageNumber}/Thumbnail/{width}/{height}

URL Parameters

pageNumber

Required. The page number for which to generate a thumbnail, starting at index 0.

width

Required. The width of the thumbnail in pixels.

height

Required. The height of the thumbnail in pixels.

Query String Parameters

DocumentID

Required. The Document ID of the requested document.

provider

Optional. The provider to which to direct the request. Can also be specified as part of DocumentID.

contentType

Optional. The content type to which to render the source document. Must be one of either be "png", or "jpeg". Defaults to "jpeg". Specifying "svg" will result in an error.

quality

Optional. Values range from 1-99. Defaults to 85. Only applicable for JPEG render format. A value of 100 implies PNG output.

Returns

The thumbnail for the requested document and page number.

Examples

Request

GET .../ImageGearService.svc/Page/q/4/Thumbnail/200/200?DocumentID=udataProviderName!myfile.pdf&quality=90

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg

<<jpeg image data>>

Page Tile

Description

Returns a tile (scaled and cropped region) of the requested document and page number. Scaling can be specified through an optional query string parameter. If scaling is specified, the image will first be scaled, then cropped according to its dimensions after scaling.

Endpoint

GET .../ImageGearService.svc/Page/q/{pageNumber}/Tile/{x}/{y}/{width}/{height}

URL Parameters

pageNumber

Required. The page number for which to generate a thumbnail, starting at index 0.

x

Required. The horizontal offset in pixels of the region from the upper left-hand corner of the page. If the x offset is out of bounds, any portion of the cropped region beyond the boundaries of the rasterized document will be filled with white pixels.

y

Required. The vertical offset in pixels of the region from the upper left-hand corner of the page. If the y offset is out of bounds, any portion of the cropped region beyond the boundaries of the rasterized document will be filled with white pixels.

width

Required. The width of the region.

height

Required. The height of the region.

Query String Parameters

DocumentID

Required. The Document ID of the requested document.

provider

Optional. The provider to which to direct the request. Can also be specified as part of DocumentID.

scale

Optional. The factor by which to scale the rasterized page before cropping. Floating point number greater than zero. Default is 1.0.

contentType

Optional. The content type to which to render the source document. Must be one of either be "png", or "jpeg". Defaults to "jpeg". Specifying "svg" will result in an error.

quality

Optional. Values range from 1-99. Defaults to 85. Only applicable for JPEG render format. A value of 100 implies PNG output.

Returns

The image tile or scaled/cropped region of the requested document and page number according to the specified parameters.

Examples

Request

GET .../ImageGearService.svc/Page/q/2/Tile/0/0/100/100?&DocumentID=myfile.pdf

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg

<<jpeg image data>>