"v3" Viewing Sessions

DEPRECATION NOTICE: The "v3" viewing sessions REST APIs have been deprecated and will be removed in a future release.

IMPORTANT: This experimental API is a work-in-progress that is not officially supported by Accusoft. Its behavior may change at any time in a future release of the product.

Available URLs

URL	Description
POST /v3/viewingSessions	Creates a new Viewing Session.
GET /v3/viewingSessions/{viewingSessionId}/content/root/metadata	Gets metadata for the Viewing Session content.
GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}	Gets PDF for a page group of the Viewing Session source.
HEAD /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}	Gets the HTTP headers that would be returned if the HEAD request's URL was instead requested with the GET method.
POST /v3/viewingSessions/{viewingSessionId}/heartbeat	Let the server know that the client is still using this Viewing Session.

POST /v3/viewingSessions

Creates a new Viewing Session.

Request

Request Headers

Name	Description
`Content-Type`	Should be `application/json`

Request Body

JSON object conforming to the following:

input (Object) Required. Specifies the input used for the Viewing Session creation.
- source (Object) Required. Identifies the source for the Viewing Session.
  - type (String) Required. The type of the source. The only valid value is:
    - "viewingPackage" An existing Viewing Package will be used as the source. Use the "v3" Viewing Package Creators API to create a Viewing Package. The Viewing Package lifetime will be extended when a Viewing Session is created.
  - packageId (String) Required. ID of the Viewing Package to use as the source.

Successful Response

Response Body

JSON object with the following properties:

viewingSessionId (String) Unique ID for this Viewing Session.

Error Responses

Status Code	JSON `errorCode`	Description
`480`	`"ResourceNotFound"`	The Viewing Package with the provided `packageId` could not be acquired. See `errorDetails` in the response body.
`480`	`"ViewingPackageIsNotComplete"`	The Viewing Package with the provided `packageId` is not complete.
`480`	`"LicenseCouldNotBeVerified"`	The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.

Example

Request

POST /v3/viewingSessions
Content-Type: application/json

{
  "input": {
    "source": {
      "type": "viewingPackage",
      "packageId": "my-viewing-package-id"
    }
  }
}

Response

HTTP 200 OK
Content-Type: application/json

{
  "viewingSessionId": "4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX"
}

GET /v3/viewingSessions/{viewingSessionId}/content/root/metadata

Gets metadata for the Viewing Session content.

Request

URL Parameters

Parameter	Description
`{viewingSessionId}`	The `viewingSessionId` which identifies the Viewing Session.

Successful Response

Response Headers

Name	Description
`Content-Type`	`application/json`
`Content-Length`	The JSON size in bytes.
`Cache-Control`	Content caching directives.

Response Body

JSON object with the following properties:

pageGroups (Array of Objects) Array of objects containing metadata on each of the page groups created for the viewing session content.
- startPage (Integer) Start page of the page group.

Error Responses

Status Code	JSON `errorCode`	Description
`404`	`"ResourceNotFound"`	No Viewing Session with the provided `viewingSessionId` could be found.
`480`	`"LicenseCouldNotBeVerified"`	The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.

Example

Request

GET /v3/viewingSessions/4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX/content/root/metadata

Response

HTTP 200 OK
Content-Type: application/json

{
  pageGroups: [
    {
      startPage: 1
    }
  ]
}

GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}

Gets PDF for a page group of the Viewing Session source.

NOTE: This request extends source Viewing Package lifetime.

Request

URL Parameters

Parameter	Description
`{viewingSessionId}`	The `viewingSessionId` which identifies the Viewing Session.
`{index}`	The zero-based index of the requested page group.

Request Headers

Name	Description
`Range`	Optional. Defines a single range of the file content, e.g. `"bytes=0-1023"` value can be used to request the first 1024 bytes. Full page group content will be requested when the header is not specified.

Successful Response

Returns HTTP 200 when full content is requested. Returns HTTP 206 when content range is requested.

Response Headers

Name	Description
`Content-Type`	`application/pdf`
`Content-Length`	The page group PDF file size in bytes.
`Cache-Control`	Content caching directives.
`Content-Range`	Returned when `Range` has been requested. The value indicates where in the full content the returned partial content belongs.

Response Body

PDF file bytes.

Error Responses

Status Code	JSON `errorCode`	Description
`404`	`"ResourceNotFound"`	No Viewing Session with the provided `viewingSessionId` or no page group with provided `index` could be found.
`480`	`"LicenseCouldNotBeVerified"`	The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.
`416`		The requested `Range` could not be satisfied. This error can be thrown when page group content doesn't contain such ranges, or when the syntactically correct `Range` header value doesn't make sense.

HEAD /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}

Gets the HTTP headers that would be returned if the HEAD request's URL was instead requested with the GET method.

NOTE: Unlike the GET /v3/viewingSessions/{viewingSessionId}/content/root/pageGroups/{index}, this route does not support a Range header.

Request

URL Parameters

Parameter	Description
`{viewingSessionId}`	The `viewingSessionId` which identifies the Viewing Session.
`{index}`	The zero-based index of the requested page group.

Successful Response

Response Headers

Name	Description
`Content-Type`	`application/pdf`
`Content-Length`	The page group PDF file size in bytes.
`Cache-Control`	Content caching directives.

Response Body

No body.

Error Responses

Status Code	Status Message	Description
`404`	`"ResourceNotFound"`	No Viewing Session with the provided `viewingSessionId` or no page group with provided `index` could be found.
`480`	`"LicenseCouldNotBeVerified"`	The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.

POST /v3/viewingSessions/{viewingSessionId}/heartbeat

Let the server know that the client is still using this Viewing Session. Use the Heartbeat API to keep the Viewing Session alive, otherwise it will self expire. Viewing Session lifetime after the last heartbeat is 5 minutes.

NOTE: Viewing Session lifetime after session creation is limited to 6 hours.

Request

Request Body

Empty.

Successful Response

Response Headers

Name	Description
`Content-Type`	`application/json`

Response Body

Empty JSON object.

Error Responses

Status Code	Status Message	Description
`404`	`"ResourceNotFound"`	No Viewing Session with the provided `viewingSessionId` or no page group with provided `index` could be found.
`480`	`"LicenseCouldNotBeVerified"`	The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.

Example

Request

POST /v3/viewingSessions/4jOOgAh-9rktzXLzst-TIXYKdbDfy-I_3vQgnzzhcpkX/heartbeat

Response

HTTP 200 OK
Content-Type: application/json

{}