Media

The Media REST API is used to download and upload videos for viewing in PrizmDoc Viewer.

Available URLs

URL	Description
GET /api/v1/media/:fileId/video	Downloads the video for viewing.
POST /api/v1/media when body is file bytes	Uploads the video for viewing.
POST /api/v1/media when body is JSON	Creates a File ID for viewing an existing video located on PrizmDoc Server’s storage.

GET /api/v1/media/:fileId/video

Downloads the video for viewing.

Parameter

Field	Type	Description
`fileId`	String	File ID returned from `/api/v1/media`.

Query Parameter(s)

Field	Type	Description
`AffinityToken`	String	Affinity Token returned on upload (only when PrizmDoc is in cluster mode).

Success 200

Field	Type	Description
`body`	ReadableStream	Byte stream of the video uploaded to `/api/v1/media`.

Success-Response

HTTP/1.1 200 OK
<video file bytes>

Error 4xx

Name	Description
`NotFound`	The `fileID` specified in the URL path was not found.

Error-Response

HTTP/1.1 404 Not Found
{ }

POST /api/v1/media when body is file bytes

Uploads the video for viewing.

Header

Field	Type	Description
`Content-Type`	String	Mime type of file. Expected to be one of `video/mp4`, `video/webm`, `video/ogg`, `application/octet-stream`.

Request Body

Field	Type	Description
`Body`	ArrayBuffer	Video file bytes.

Success 200

Field	Type	Description
`fileID`	String	Identifier associated with uploaded file.
`affinityToken`	String	Identifier indicating the PrizmDoc Server instance that processed the request (only when running PrizmDoc Server in cluster mode).

Success-Response

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
}

Success-Response with Affinity Token

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A",
  "affinityToken":"zTfGFeeRXKxPF5o4HgnFFgZ6YU6bcbvMsJdJciYJemo="
}

Error 4xx

Name	Description
`FeatureNotLicensed`	The file exceeds evaluation limit of 5MB.
`MissingInput`	Content-Type header is missing.
`InvalidInput`	Content-Type header is not a valid value.

413 `FeatureNotLicensed`

HTTP/1.1 413 FeatureNotLicensed
{
  "errorCode": "FeatureNotLicensed",
  "errorDetails": {
    "in": "body",
    "at": "length",
    "expected": {
      "lessThanOrEqualTo": 5242880
    }
  }
}

480 `MissingInput`

HTTP/1.1 480 MissingInput
{
  "errorCode": "MissingInput",
  "errorDetails": {
    "in": "headers",
    "at": "Content-Type",
    "expected": {
      "oneOf": [
        {
          "value": "video/mp4"
        },
        {
          "value": "video/webm"
        },
        {
          "value": "video/ogg"
        },
        {
          "value": "application/octet-stream"
        }
      ]
    }
  }
}

480 `InvalidInput`

HTTP/1.1 480 InvalidInput
{
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "headers",
    "at": "Content-Type",
    "expected": {
      "oneOf": [
        {
          "value": "video/mp4"
        },
        {
          "value": "video/webm"
        },
        {
          "value": "video/ogg"
        },
        {
          "value": "application/octet-stream"
        }
      ]
    }
  }
}

POST /api/v1/media when body is JSON

Creates a File ID for an existing video located on PrizmDoc Server’s storage. This feature is only available for single server configurations in licensed mode and requires the central configuration parameter workFiles.external.file.directory to be set on PrizmDoc server. Please contact info@accusoft.com to obtain a license.

NOTE: If the video file is modified after the creation of the File ID, consequent GET /api/v1/media/:fileId/video requests will download the modified version.

Request Header

Field	Type	Description
`Content-Type`	String	Must be `application/json`.

Request Body

A JSON object that conforms to the following:

type (String) Required. The type of storage. Must be “file”.
fileExtension (String) Required. Extension of the video. Supported extensions are .mp4, .ogg, and .webm
file (Object) Required. Object containing information of the “file” storage type.
- path (String) Required. Relative path to the video which should be accessible by the PrizmDoc Server. The video file must be located inside the directory specified in PrizmDoc Server's workFiles.external.file.directory central configuration parameter.

Example:

{
    "type": "file",
    "fileExtension": "mp4",
    "file": {
      "path": "./videos/presentations/video.mp4"
    }
}

Successful Response

Response Header

Field	Type	Description
`Content-Type`	String	`application/json`.

Response Body

A JSON object with the following properties:

fileID (String) Identifier associated with local video.

Example:

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
}

Error Responses

Status Code	JSON errorCode	Description
413	`FeatureNotLicensed`	The server is not licensed to use the requested feature or API.
480	`MissingInput`	Content-Type or object in body is missing.
480	`InvalidInput`	Unsupported file extension.
480	`ExternalContentNotFound`	The file specified in the path does not exist or is not accessible.
480	`IncorrectUsage`	`workFiles.external.file.directory` has not been configured in PrizmDoc Server, an absolute path has been provided for the file, or the relative path points outside of the directory specified in `workFiles.external.file.directory`.

413 `FeatureNotLicensed`

HTTP/1.1 413 FeatureNotLicensed
{
  "errorCode": "FeatureNotLicensed",
  "errorDetails": "The server's license does not allow the use of the requested feature or API."
}

480 `MissingInput`

HTTP/1.1 480 MissingInput
{
  "errorCode": "MissingInput",
  "errorDetails": {
   "in": "body",
   "at": "file",
   "expected": {
     "type": "object"
    },
    "when": [
      {
        "otherInput": {
          "in": "body",
          "at": "type",
          "is": {
            "value": "file"
          }
        }
      }
    ]
  }
}

480 `InvalidInput`

HTTP/1.1 480 InvalidInput
{
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "body",
    "at": "fileExtension",
    "expected": {
      "oneOf": [
        {
          "value": "mp4"
        },
        {
          "value": "webm"
        },
        {
          "value": "ogg"
        }
      ]
    }
  }
}

480 `ExternalContentNotFound`

HTTP/1.1 480 ExternalContentNotFound
{
  "errorCode": "ExternalContentNotFound"
}

480 `IncorrectUsage`

HTTP/1.1 480 IncorrectUsage
{
  "errorCode": "IncorrectUsage"
}