Introduction
The markup layers REST API is used by our viewer to save and load markup (annotations and redactions) in our newer JSON format.
Background
Our viewer has two different markup persistence modes it operates in:
- Legacy XML markup mode - In this mode, the viewer saves and loads markup data in our older, legacy XML format using the markup XML REST API. This is the default viewer behavior. DEPRECATION NOTICE: The Legacy XML Markup Mode has been deprecated and will be removed in a future release. If you are currently using it, we recommend you use our updated JSON Markup Mode instead.
- JSON markup mode - In this mode, the viewer saves and loads markup data in our newer JSON format using this markup layers REST API. This mode applies when the viewer is configured with
annotationsMode
set to'LayeredAnnotations'
(recommended).
We recommend you always instantiate the viewer with annotationsMode
set to 'LayeredAnnotations'
so that it will operate in the new JSON markup mode. When you do this, the viewer will use this markup layers REST API to save and load markup data in our newer JSON format.
If your application needs to access or manipulate the annotation JSON created by your end users, you will need to use this REST API.
A set of markup data is accessed by markupId
. But, because this REST API was designed for use by our viewer, all operations are based upon a viewing session. In order to get access to a set of markup data by markupId
, you first must create a “dummy” viewing session, specifying the markupId
you want to access via the source.markupId
property of your POST /ViewingSession
request.
However, because source.markupId
is optional when creating a viewing session, you may not know the markupId
to use. Fortunately, as long as you still know the information about the source document and how you created the original viewing session for your end user, there is still a way to access the markup data. When a viewing session is created without a source.markupId
specified, we will automatically calculate a markupId
value based upon the other source
object properties. So, if you did not specify an explicit source.markupId
when creating the original viewing session for your end user, you can still access the markup data that end user saved by creating a new “dummy” viewing session with exactly the same set of source
properties. For more information about the source
object options you can pass in on a POST /ViewingSession
request, see the POST /ViewingSession
API reference.
Available URLs
URL | Description |
---|---|
GET /MarkupLayers/u{viewingSessionId} | Gets the list of all available markup layers for the particular document. |
POST /MarkupLayers/u{viewingSessionId} | Creates a new markup layer using the provided data. |
GET /MarkupLayers/u{viewingSessionId}/{layerRecordId} | Gets a particular layer record from the server. |
PUT /MarkupLayers/u{viewingSessionId}/{layerRecordId} | Updates an existing markup layer record with new data. This will overwrite all old data with the new uploaded data. |
DELETE /MarkupLayers/u{viewingSessionId}/{layerRecordId} | Deletes a markup layer record from the server. |
GET /MarkupLayers/u{viewingSessionId}
Routes key: GetMarkupLayers
Gets the list of all available markup layers for the particular document.
GET pas_base_url/MarkupLayers/u1234
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "layer name 1",
"layerRecordId": "2fee93fadf2ed11df",
"originalXmlName": ""
},
{
"name": "layer name 2",
"layerRecordId": "32f993b09fb0f2236",
"originalXmlName": ""
}
]
Error Responses
When the document cannot be identified based on the viewing session:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"errorCode": "BadGateway"
}
When the server's license could not be verified:
HTTP/1.1 480 LicenseCouldNotBeVerified
Content-Type: application/json
{
"errorCode": "LicenseCouldNotBeVerified"
}
When an unknown error occurs while gathering data:
HTTP/1.1 580 Server Error
Content-Type: application/json
{
"errorCode": "InternalError"
}
POST /MarkupLayers/u{viewingSessionId}?documentId={documentId}
Routes key: CreateMarkupLayer
Creates a new markup layer using the provided data.
In order to keep Markup intact with your rendered documents even after future PrizmDoc and system updates, you should create a PDF Viewing Package for this document and use the markup with this viewing package instead of the original document going forward. You can use the POST MarkupLayers
request to trigger the creation of a viewing package for the current document. Use the documentId
URL parameter to specify the viewing package to be created. If the viewing package does not exist yet, PrizmDoc will start the creation of a new PDF Viewing Package in the background and return you the viewing package creator process ID, so you can check its status if necessary. See Keeping Markup Intact With Your Documents for more details.
URL Parameters
Parameter | Description |
---|---|
{viewingSessionID} |
The ID of the viewing session associated with the request. |
{documentId} |
the ID of the viewing package (documentId ) to be associated with the markup. If the documentId is provided and the viewing package does not exist yet, its creation will be started in the background. |
Example: Saving a Markup Layer
POST pas_base_url/MarkupLayers/u1234
Content-Type: application/json
{
"name": "layer name 1",
"comments": [],
"data": {},
"marks": [{ array of mark objects }]
}
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"layerRecordId": "2fee93fadf2ed11df"
}
Error Responses
When the document cannot be identified based on the viewing session:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"errorCode": "BadGateway"
}
When the server's license could not be verified:
HTTP/1.1 480 LicenseCouldNotBeVerified
Content-Type: application/json
{
"errorCode": "LicenseCouldNotBeVerified"
}
When an unknown error occurs while gathering data:
HTTP/1.1 580 Server Error
Content-Type: application/json
{
"errorCode": "InternalError"
}
Example: Saving a Markup Layer and Specifying a Document ID
POST pas_base_url/MarkupLayers/u1234?documentId=myUniqueDocumentId
Content-Type: application/json
{
"name": "layer name 1",
"comments": [],
"data": {},
"marks": [{ array of mark objects }]
}
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"layerRecordId": "2fee93fadf2ed11df",
"viewingPackageCreatorProcessId": "wert54w4rser4345efg"
}
Error Responses
When the viewing package specified by the documentId
query parameter already exists and is not compatible with the current viewing session:
HTTP/1.1 480
Content-Type: application/json
{
"errorCode": "InputConflictsWithViewingPackage",
"errorDetails": {
"in": "queryString",
"at": "documentId",
"when": [{
"otherInput": {
"in": "viewingSession",
"at": "<path to the conflicting viewing session parameter>"
}
]
}
}
When the viewing session was created from a viewing package and the documentId
query parameter does not match the documentId of the existing viewing package:
HTTP/1.1 480
Content-Type: application/json
{
"errorCode": "InputConflictsWithViewingPackage",
"errorDetails": {
"in": "queryString",
"at": "documentId",
"when": [{
"otherInput": {
"in": "viewingSession",
"at": "source.documentId"
}
]
}
}
GET /MarkupLayers/u{viewingSessionId}/{layerRecordId}
Routes key: GetMarkupLayer
Gets a particular layer record from the server.
GET pas_base_url/MarkupLayers/u1234/2fee93fadf2ed11df
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 200 OK
Content-Type: application/json
{
...markup layer data...
}
Error Responses
When the markup layer record does not exist:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errorCode": "NotFound"
}
When the document cannot be identified based on the viewing session:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"errorCode": "BadGateway"
}
When an unknown error occurs while gathering data:
HTTP/1.1 580 Server Error
Content-Type: application/json
{
"errorCode": "InternalError"
}
PUT /MarkupLayers/u{viewingSessionId}/{layerRecordId}
Routes key: UpdateMarkupLayer
Updates an existing markup layer record with new data. This will overwrite all old data with the new uploaded data.
PUT pas_base_url/MarkupLayers/u1234/2fee93fadf2ed11df
Content-Type: application/json
NOTE: See the Base URL for PAS topic for more information.
Alternatively, the POST
method is supported for this request in combination with an X-HTTP-Method-Override
header, as such:
POST pas_base_url/MarkupLayers/u1234/2fee93fadf2ed11df
Content-Type: application/json
X-HTTP-Method-Override: PUT
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 200 OK
Error Responses
When the markup layer record does not exist:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errorCode": "NotFound"
}
When the document cannot be identified based on the viewing session:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"errorCode": "BadGateway"
}
When an unknown error occurs while gathering data:
HTTP/1.1 580 Server Error
Content-Type: application/json
{
"errorCode": "InternalError"
}
DELETE /MarkupLayers/u{viewingSessionId}/{layerRecordId}
Routes key: DeleteMarkupLayer
Deletes a markup layer record from the server.
DELETE pas_base_url/MarkupLayers/u1234/2fee93fadf2ed11df
NOTE: See the Base URL for PAS topic for more information.
Alternatively, the POST
method is supported for this request in combination with an X-HTTP-Method-Override
header, as such:
POST pas_base_url/MarkupLayers/u1234/2fee93fadf2ed11df
X-HTTP-Method-Override: DELETE
NOTE: See the Base URL for PAS topic for more information.
Successful Response
HTTP/1.1 204 No Content
Error Responses
When the markup layer record does not exist:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errorCode": "NotFound"
}
When the document cannot be identified based on the viewing session:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
"errorCode": "BadGateway"
}
When an unknown error occurs while gathering data:
HTTP/1.1 580 Server Error
Content-Type: application/json
{
"errorCode": "InternalError"
}