You are here

You are here

REST API - Content API

The Content API’s purpose is to allow upload, download, and versioning of documents in SpringCM. 

The URL’s for Content API operations are generally discovered as properties of the Object API’s Document and Folder objects.  For performance reasons, the Content API uses different base URL’s than the Object and Task API.  See the Base URLs (link) section for more information.

Document Download

The URI for downloading a document via the REST API is in general the same path as getting document object via the Object API, however the base URL is different for the Object and Content API.  As a convenience, the Document object contains a DownloadDocumentHref property.  A GET to this URI will retrieve the document content stream in its native format.  For certain document types SpringCM will create copies of the document in different formats.  To download the document in a format other than the native content type, specify the desired content type via the ACCEPT header.  The following document types are supported:

  • Native – Not sending an ACCEPT header or specifying an accept header of native will download the document in the original format it was uploaded.  This is supported for all documents in SpringCM.
  • PDF – This is supported for native PDFs, Word, Excel, Powerpoint, and text files (check this).  Specify the content type of application/pdf to download the PDF rendition of the document.  Note that the creation of the PDF document is an asynchronous operation in SpringCM.  A newly uploaded or created document can be downloaded immediately in its native format, however the PDF rendition will not be available for download until a short time after upload/creation.  The PageCount property of a document will be populated as part of PDF creation.  Generally, if the PageCount property of the document object is greater than zero, the PDF rendition of the document can be requested.  If a PDF rendition is not available for a document, a 404 response will be returned.
  • Text – SpringCM will execute OCR (Optical Character Recognition) for PDFs, most image types, and Office documents (check this) as part of full text indexing the documents for search.  SpringCM stores the OCR’d text and makes it available for download via the Content API.  To download the OCR’d text, specify text/plain in the ACCEPT header.  If no text is available for a given document, a 404 response is returned.  OCR text extraction for a document is an asynchronous process in SpringCM, so it will not available for a short time after newly creating or uploading a document in SpringCM.
  • Image – For any document that has a PDF rendition in SpringCM, a PNG image of a given page at a given zoom level can be requested.  To request the png download of a document specify image/png in the ACCEPT header.  If a specific page or zoom is not requested, page 1 of the document at the default zoom (generally 100%) set for the account will be returned.  To ask for a specific page, the page query string parameter may be appended set to the specific page to be download.  If a zoom level other than the default zoom is needed, the zoom query string parameter may be appended to the URI.  Valid values for zoom are thumbnail, 50, 75, 100, 125, 150, and 200.  Unlike PDF’s and OCR text, png images are generated on the fly when requested via the API and then cached for an indefinite period of time.  If the image is available from the cache at the time of the request, it will be returned immediately.  If it is not, it will be queued for creation and a response similar to the one shown below will be returned.  SpringCM does not support a strict SLA for png creation time, however it is generally available within a few seconds and developers using this request method should code retry logic accordingly.
Error object when a document preview image is not yet available

{
  "Error": {
    "HttpStatusCode": 404,
    "UserMessage": "Document Not Yet Available",
    "DeveloperMessage": "Document Not Yet Available",
    "ErrorCode": 119,
    "ReferenceId": "77e94e25-c490-4801-9799-d297ff6730ac"
  }
}

Document Download - Native Document Hashes

When downloading most documents, SpringCM will add a custom X-SpringCM-Content-SHA256 header to the header collection.  As the name implies, this will be a base64 encoded SHA256 hash of the native content that can be used to verify the download.  Hashes of content other than the native file are not supported at this time.

In some cases, it maybe be desirable to retrieve the SHA256 hash generated by SpringCM on the server side without downloading the entire document.  To enable this, a HEAD request may be made to the download URL to only retrieve the download headers without asking the server to send the full document body in the response.

Document Upload – New Document Creation

There are 2 items that are required when uploading a new document to SpringCM, the target parent folder for the document and the document’s name.  The URI template for uploading a document to a particular folder is specified on the object API folder object in the CreateDocumentHref property.  For general reference the URI will be as follows:

Document Upload Format

https://apiupload[datacenter].springcm.com/[api version]/folders/[folder identifier]/documents{?name}

The {?name} is the RFC 6570 (link) nomenclature to specify that a name parameter must be added to the query string to indicate the target name of the document being uploaded.  This is only required if a document is being streamed to the upload endpoint.

One or more documents may also be uploaded via the multipart/form-data content type.  In this case, the native document names will be used and names are not appended to the query string.

If a file is successfully uploaded, the server will return a 201 Created response and the document object of the uploaded file.  In the case where multiple documents are successfully uploaded in a multi-part form, an array of document objects will be returned.

Document Upload – Versioning a Document

The Lock object is a child object of a document and is used to manage document check in, check out, and versioning.  The lock object is also used to monitor when a document is sent out for electronic signature, as this is a special type of document check out.  The document lock object can have the following properties:

  • IsLocked (boolean): If the document is locked,
  • LockDate (string): When the document was locked. Null if the document is not locked,
  • Type (string): Type of document lock. Possibilities: not checked out, checked out, out for signature,
  • Comment (string): Comment provided by the user when the document was locked,
  • LockOwner (User): The owner of the lock. Null if not locked,
  • CheckInHref (string): If the document is checked out, this is the URI where it can be checked in,
  • SignatureHref (string): If the lock due to a pending signature(s), this is the URI for checking signature status,
  • Href (string): Uri where the object can be retrieved.

The lock object for a document is retrieved either by a GET request to the URI specified in the documents Lock.Href or by adding expand=lock to the query string when requesting the document object.  A lock object on a document that is not checked out will be similar to the following:

Sample Lock Object

{
  "Lock": {
    "IsLocked": false,
    "Type": "NotCheckedOut",
    "CheckInHref": "https://apiuploadna11.springcm.com/v201411/documents/133d190e-8aeb-e411-a9d7-3863bb335c14"
  }
}

The document can be versioned by making a POST request to the CheckInHref of the lock object of the document.  Note that is this is the same URI as the document object itself but has substituted the API upload base URL for the Object API base URL.

In the case where a document must be checked out by a user so that no one else may upload a document until the current user is finished with it, an empty POST request may be made to the URI specified in the Lock.Href property.  To cancel the checkout a DELETE request may be made to the same URI.  To check the document back in a PUT or PATCH request can be made to the same URI.