Using the Inbound Documents API

Third party software vendors can integrate with Opus 2 via REST API. Once set up, a user can get a token from the application and then they can give that to a third party application that has been set up to read and write content via the API as an alternative to logging in and viewing and editing content through the user interface.

For the Documents API, there are two types of connections, inbound and outbound. This article describes the INBOUND Documents API for integrations whereby third-party vendors can control users and data in the Platform v8 environment.  

To see examples of requests and responses using cURL for each endpoint, see the attached PDF of the Swagger output for this API at the bottom of this article. 

Prerequisites

To use the Inbound Documents REST API,  an Operator must switch on the following settings:  

System-wide setting:              Allowing access to the integrations API

Project specific setting:          Download docs via API

Create a user (token owner) who has Read Write access to the project containing the resource being read or written.

Structure of the API URL

The API URL is structured as follows:

{tenant url}/ENDPOINT -i -X VERB \  -H ‘X-API-Token:TOKEN -d {data}

where:

Client codes

400 Bad Request response: You sent invalid JSON or the incorrect type of JSON values. Example: Invalid timestamp format. Use format xxxxx.

409 You cannot delete the only version of a document

Error codes

403: You do not have permission to delete this file

404: Request for a non-existent entity. Example: Document version not found.

500: Backend error

Return codes

HTTP verbs

Working with tokens and making requests

The token should be sent as the X-Api-Token header. This identifies the user making the request and determines if the request will be accepted.  Once the user making the request (the owner of the token) has been identified, then the request proceeds with the permissions and access rights of that user. Not all API requests are accessible to all users.

For a request to complete successfully, the token owner must have access to the project containing the resource being read or written and must have the appropriate capabilities within that project to create, read, or update the resource according to the operation being performed. Therefore, this user should be created by default on each project created within Opus 2 as part of the project template settings as per the Prerequisites above.

Payload fields for token API

Payload JSON for token API

{"userId":"userId","name":"ATokenName"}

Inbound documents API endpoints

Performance considerations

There are no API-specific performance considerations. Operations resulting from calls to the API are handled by the same back-end services as interactive events from users accessing the system via the web interface, and have the same performance profile as the application as a whole.

API rate limiting

The system supports API rate limiting to prevent applications using the API from overwhelming the system and harming the interactive user experience. This is configurable on a per-client basis with a  initial default rate limit of 50 requests per minute.

The API follows a conventional REST model but does not implement any particular specification. Pagination is supported on all the endpoints that can return significant volumes of data (documents, folders, worksheet record etc). 

Related articles

Features only accessible in Operator mode

Obtaining a REST API authentication token

If you require functionality not provided by the existing REST API, contact Opus 2 Platform Support.