PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Pre-Conversion to PDF Support / "v3" Viewing Sessions
In This Topic
    "v3" Viewing Sessions
    In This Topic

    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
    
    {}