This information is common to all our APIs, so make sure to read it carefully.
In order to use our API, you will need an authentication token. You can request your token to our team at firstname.lastname@example.org.
Each token will have access to the APIs that you request and only those. We strongly suggest to have an independent token for each API, but we understand that it may be useful to have different combinations.
Every call to our APIs must carry this token in the request headers, in order to ensure that you and only you can access your data. Any requests made without authentication will fail.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
We use JSON-encoded requests and responses.
Each API end-point has its own set of parameters. They are divided in:
- Request parameters: These parameters are part of the URL and are used to identify the resource we are interested in. For example, if we are want to get the structure for a certain template, we will need to provide the template unique identifier in the URL.
- Query parameters: These parameters are attached to the request and are used to modify the response we get when requesting the resources we are interested in.
- Request body: these parameters are specified in the request body and are used to create or modify the resource that interests us. For example, if we want to create a new document, we will also have to provide the name and content of the document.
We will divide our response cases in two:
- Success: Everything works as expected. Depending on the end-point we used, we could receive an empty response, for example if we delete a document, or a set of parameters resulting from the operation we requested, like the document unique identifier when we create a document.
- Error: Something didn't work as expected. We will get a message explaining what went wrong. We will also get a date and a requestId which will be useful if we need more details.
All our APIs have an status endpoint to check if the corresponding service is available. It will always return a 200 HTTP status as well as the API version.
We can check the overall status of the APIs in our status dashboard.