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

"ImageGearService.svc" should be placed within your server root directory.
All Web.config settings pertaining to service binding or otherwise can either be configured by manually editing Web.config or by using the Web.Config Editor.
All ImageGear.Web endpoints are documented here using relative urls from "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:

ViewingSessionProvider.cs
ViewingSessionImageDataConnection.cs
ViewingSessionArtDataConnection.cs
Web.config

Models:

ViewingSession.cs

Controllers:

ViewingSessionController.cs

Sample Implementation:

sample.js

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}

Each data provider added must be assigned a name which can be used to refer to it explicitly when making requests to the back-end.
- Once a data provider selection is made, the stream identifier is passed to the data provider to retrieve the stream.
- A data provider selection can also be made through the optional query string parameter "provider=dataProviderName".
The parse token is also configurable and defaults to an exclamation mark (‘!’). This token separates the data provider identifier from the stream identifier.
A request for a DocumentID without a parse token will be interpreted in its entirety as a stream identifier and will be routed to the default data provider.
- Document IDs as used internally may or may not be encoded using a form of base64 encoding. Document IDs which are un-encoded are prefixed with a ‘u’ and those which are encoded are prefixed with an ‘e’.
- When utilizing any of the following endpoints, you can only specify Document IDs in their un-encoded form, so any Document IDs must be prefixed with the character ‘u’. Make sure to use encodeURIComponent() on the Document IDs when constructing the urls to make requests.

Viewing API - Overview of REST API Endpoints

Uploading

[POST] .../ImageGearService.svc/Document

Document and Page Information

[GET] .../ImageGearService.svc/Document/q/Attributes
[GET] .../ImageGearService.svc/Page/q/{pageNumber}/Attributes

Page Conversion and Rasterization

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

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.
Query String Parameters	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.
Query String Parameters	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.
Query String Parameters	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.
Query String Parameters	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.
Query String Parameters	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.
Query String Parameters	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>>