Documents
{
id: string
user_id: string
name: string
pdf_url: string // Location of the converted/optimized PDF
source_url: string // Location of the original document
renders: [
{
id: string
plugin: string // Which service was used to create this render. Only pdfjs is currently supported.
status: string // Can be: pending, done, error, deleted
started_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
created_at: number
}
]
created_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
events: [] // Only used by the Admin Panel
panda_push: {} // Only used by the Admin Panel
}
- Create a Document
- Download a Document
- Get all Documents
- Get a Document
- Update a Document
- Rotate a Document Page
- Remove a Document Record
- Remove Document Files
- Single Re-render
- Batch Re-render
- Reload Crocodoc Annotations
Intro
DocViewer keeps a Document record for every document that is converted or rendered. The Document record is simply a listing of information about the document, with an ID and a URL for accessing the file itself. In order to view a file in DocViewer, the client must first Create a Document, then Create a Session, and then Download the PDF. The other endpoints listed below are used primarily by the Admin Panel.
Create a Document
POST /1/documents
Creates a Document Record in DocViewer and starts document conversion. This is
the first step of viewing a document in DocViewer. This
endpoint returns before the document finishes conversion; status will be queued
.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Body:
{
url: string
name: string
preferred_plugin: string
region: string // The AWS region the call is originating from. Used in conjunction with Canvas to identify records that are in different Canvas and DocViewer regions.
}
Responses
200
Returns a Document Object
Example Call
POST http://canvadocs.docker/1/documents
Content-Type: application/json
Authorization: Token apikey
{
"name": "pdf.pdf",
"preferred_plugin": "pdfjs",
"url": "http://www.pdf995.com/samples/pdf.pdf",
"region": "us-east-1"
}
200 OK
{
"type": "document",
"id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"name": "pdf.pdf",
"source_url": "http://www.pdf995.com/samples/pdf.pdf",
"created_at": "2018-04-11T19:23:25.000Z",
"renders": [
{
"plugin": "pdfjs",
"status": "queued",
"started_at": "2018-04-11T19:23:25.090Z",
"created_at": 1523474605
}
]
}
Download a Document
GET /1/sessions/{session_id}/file/{filename}
Downloads the converted PDF specified by the session_id jwt
and the filename (the name
property on the Document Object). This
endpoint requires that the client first launch a session.
This is used by clients (including the DocViewer Client) to get
the PDF and display it to the user.
Parameters
Query:
session_id: string
filename: string // The name of the file to download, as specified in the Document Object
Responses
200
Returns the converted .pdf file
Example Call
GET http://canvadocs.docker/1/sessions/eyJhbGciOiJI.../file/file.pdf
200 OK
// The .pdf file was then downloaded
Get all Documents
GET /1/documents
Returns a list of documents in the current environment. The list is paginated. This endpoint is used by the Admin Panel to display the list of recent documents.
Parameters
This endpoint requires authorization
Headers:
Authorization: Token KEY_HERE
Responses
200
Returns an array of Document Objects
{
"document_collection": {
"entries": [
Document Object
]
},
"startKey": string,
"documentCount": number
}
Example Call
GET http://canvadocs.docker/1/documents
Authorization: Token apikey
200 OK
{
"document_collection": {
"entries": [
{
"renders": [
{
"started_at": "2018-04-10T19:17:46.476Z",
"created_at": 1523387866,
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
"plugin": "pdfjs",
"status": "done"
}
],
"user_id": "dev",
"name": "pdf.pdf",
"created_at": 1523387866,
"pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
"source_url": "http://www.pdf995.com/samples/pdf.pdf"
},
...
]
},
"startKey": "{\"user_id\":\"dev\",\"created_at\":1522358228,\"id\":\"kF52gK9ch5tuaGTEc77eJ7YaGfH3Cr\"}",
"documentCount": 222
}
Get a Document
GET /1/documents/{document_id}
Returns information about a single document. This endpoint is used by the Admin Panel to generate a document's info page.
Parameters
This endpoint requires authorization
Headers:
Authorization: Token KEY_HERE
Query:
document_id: string
Responses
200
Returns a Document Object
Example Call
GET http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_
Authorization: Token apikey
200 OK
{
"type": "document",
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
"name": "pdf.pdf",
"source_url": "http://www.pdf995.com/samples/pdf.pdf",
"pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
"created_at": "2018-04-10T19:17:46.000Z",
"renders": [
{
"started_at": "2018-04-10T19:17:46.476Z",
"created_at": 1523387866,
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
"plugin": "pdfjs",
"status": "done"
}
],
"events": [...],
"panda_push": {...}
}
Update a Document
PUT /1/documents/{document_id}
Updates the information on a Document Record. Used by the Admin Panel to update a document's source URL.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Query:
document_id: string
Body:
Requires all or part of a Document Object
Responses
200
Returns a Document Object
Example Call
PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_
Content-Type: application/json
Authorization: Token apikey
{ "source_url": "s3://canvadocs-assets/Kyox5NbveINdJ9mXv26lxrD_Ph1W7W/uploadedOriginal" }
200 OK
{
"renders": [
{
"started_at": "2018-04-10T19:17:46.476Z",
"created_at": 1523387866,
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
"plugin": "pdfjs",
"status": "done"
}
],
"user_id": "dev",
"name": "pdf.pdf",
"created_at": 1523387866,
"pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
"id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
"source_url": "s3://canvadocs-assets/Kyox5NbveINdJ9mXv26lxrD_Ph1W7W/uploadedOriginal"
}
Rotate a Document Page
PUT /1/sessions/{session_id}/documents/{document_id}/rotate
Saves a rotation on the document record. Acceptable rotation degrees are: 0, 90, 180, 270.
Parameters
Query:
pageNumber: number
rotationDegrees: number
Responses
200
Returns a Document Object
403
{
"error": "cannot rotate the page because the page contains annotations"
}
Example Call
PUT http://canvadocs.docker/1/sessions/eyJhb.../documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_/rotate
Content-Type: application/json
200 OK
{
"pageNumber": 0,
"rotationDegrees": 90
}
Remove a Document Record
DELETE /1/documents/{document_id}
Deletes the document record. Does not remove any of the actual files.
Parameters
This endpoint requires authorization
Headers:
Authorization: Token KEY_HERE
Query:
document_id: string
Responses
204
Example Call
PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_
Authorization: Token apikey
204 No Content
Remove Document Files
DELETE /1/documents/{document_id}/s3
Deletes the converted PDF file, and marks the document record as deleted. Used by the Admin Panel when deleting documents.
Parameters
This endpoint requires authorization
Headers:
Authorization: Token KEY_HERE
Query:
document_id: string
Responses
204
Example Call
PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_/s3
Authorization: Token apikey
204 No Content
Single Re-render
POST /1/documents/{document_id}/retry?plugin={plugin}
Starts the rendering process for a single document. Used by the Admin Panel for re-rendering documents.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Query:
document_id: string
plugin: string // The only supported value is "pdfjs"
Responses
202
Returns a Document Object
Example Call
POST http://canvadocs.docker/1/documents/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/retry?plugin=pdfjs
Content-Type: application/json
Authorization: Token apikey
202 Accepted
{
"type": "document",
"id": "RiTsY3DfuJiehyjdvYSkeXEuHyl3M6",
"name": "pdf.pdf",
"source_url": "s3://canvadocs-assets/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/uploadedOriginal",
"pdf_url": "s3://canvadocs-assets/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/file.pdf",
"created_at": "2018-04-11T20:11:39.000Z",
"renders": [
{
"plugin": "pdfjs",
"status": "queued",
"started_at": "2018-04-11T20:14:59.312Z"
}
]
}
Batch Re-render
POST /1/render_documents
Starts the rendering process for several documents. Useful when needing to re-render an entire assignment worth of documents. See the Re-rendering Canvas Files page for details on gathering the information needed for this call.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Body:
;[
{
document_id: string
}
]
Responses
202
;[
{
document_id: string,
status: string // should be "queued"
}
]
Example Call
POST http://canvadocs.docker/1/render_documents
Content-Type: application/json
Authorization: Token apikey
[
{ "document_id":"RiTsY3DfuJiehyjdvYSkeXEuHyl3M6" },
{ "document_id":"ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ" }
]
202 Accepted
[
{
"document_id": "RiTsY3DfuJiehyjdvYSkeXEuHyl3M6",
"status": "queued"
},
{
"document_id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"status": "queued"
}
]
Reload Crocodoc Annotations
POST /1/documents/{document_id/reloadCrocAnnotations}
At some time in the distant past, DocViewer used a Crocodoc client rather than the DocViewer Client. Annotations were saved by Crocodoc in a different format. When we switched over to the DocViewer Client we started converting Crocodoc annotations to DocViewer annotations, on demand. If for some reason the conversion did not work well, this endpoint can be used to re-run the conversion. The Admin Panel has an option for this.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Query:
document_id: string
plugin: string // The only supported value is "pdfjs"
Responses
200
Example Call
POST http://canvadocs.docker/1/documents/ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ/reloadCrocAnnotations
Authorization: Token apikey
200 OK
"No Crocodoc data exists for this document"