REST API Reference
Contents:
You can use provided by elDoc REST API to build add-ons for elDoc system, develop integrations between elDoc and other applications, or script interactions with elDoc. This page provides documentation for the REST resources available in elDoc, along with expected HTTP response codes and sample requests.
Authentication & Authorization
elDoc REST API authentication is based on the JWT technology. Authentication token to be provided as Authorization
header with each request.
Authorization: Bearer XXXXX.YYYYY.ZZZZZ
For the specific requirements on the JWT claims please see the respective pages specific to the API version, as security requirements may change from API version to version.
It is highly recommended to use the latest available version of API only and block access to the deprecated API versions.
Security principles
All accesses are based on the security rights assigned to the account on behalf of which request is executed. This is related to all parts of the API and especially for the API related to working with documents in the system: besides the assigned Roles & Groups to the user account specific accesses assigned per document are also considered by the system.
URI Structure
elDoc's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The elDoc REST API uses JSON as its communication format, and the standard HTTP methods like GET
, PUT
, POST
and DELETE
(see API descriptions below for which methods are available for each resource). URIs for elDoc's REST API resource have the following structure:
https://host:port/api/v2/api-name/resource-name/resource-path-param?param1=value1¶m2=value2
Where:
api
- static partv2
- stands for api version to be used, like v2api-name
- stands for the functionality name to be usedresource-name
- stands for resource or action to be calledresource-path-param
- stands for additional resource specific path paramsparam1=value1
- stands for additional resource specific params
Experimental methods
Methods marked as experimental may change without an earlier notice. Please follow our release-notes and be prepared for making necessary adjustments to those methods in case required.
Special request and response headers
- X-Error - Response header contains information about error, if any present
- X-Error-Code - Response header contains internal error code, if any present
- X-Total-Count - Response header contains number of total items found (e.g.: total number of records, documents, or pages in the document)
Standard response codes
Code | Description |
---|---|
200 - OK | Everything worked as expected |
201 - Created | Request successfully processed, new entry was created |
204 - No Content | Request successfully processed, no entity is returned in response |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter or validation error |
401 - Unauthorized | No valid API JWT token provided |
402 - Request Failed | The parameters were valid but the request failed |
403 - Forbidden | The API key doesn't have permissions to perform the request |
404 - Not Found | The requested resource doesn't exist |
409 - Conflict | The request conflicts with another request |
429 - Too Many Requests | Too many requests hit the API too quickly |
500, 502, 503, 504 - Server Errors | Something went wrong on elDoc's end (these are rare) |
Last modified: May 12, 2023