REST API Reference

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/v1/api-name/resource-name/resource-path-param?param1=value1&param2=value2

Where:

  • api - static part
  • v1 - stands for api version to be used, like v1
  • api-name - stands for the functionality name to be used
  • resource-name - stands for resource or action to be called
  • resource-path-param - stands for additional resource specific path params
  • param1=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


Standard response codes

CodeDescription
200 - OKEverything worked as expected
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter
401 - UnauthorizedNo valid API JWT token provided
402 - Request FailedThe parameters were valid but the request failed
403 - ForbiddenThe API key doesn't have permissions to perform the request
404 - Not FoundThe requested resource doesn't exist
409 - ConflictThe request conflicts with another request
429 - Too Many RequestsToo many requests hit the API too quickly
500, 502, 503, 504 - Server ErrorsSomething went wrong on elDoc's end (these are rare)