data2check documentation – Using the API
Table of contents
1. Purpose
Even without using the free data2check web interface, documents can be checked. With the help of a simple REST API, the available checks can be integrated into other services, such as Content Management Systems.
2. Creating an API token
In order to be able to use the REST API, a so-called "API token" must be created first. For this purpose, you have to select »API tokens« in the data2check user management, on the right-hand side of the main menu (see figure 1, orange circle).
Figure 1: The data2check user management - API tokens.
Now, the API token administration appears. Please click on the green »Create API token« button (see figure 2), to create a token.
Figure 2: API token administration - Creating an API token.
On the following page, API tokens can be displayed, renewed (green »Refresh API token« button) and deleted (red »Delete API token« button). Per user, only one API token at a time is active and can be used for any available configuration (see figure 3).
Figure 3: The current API token (exemplary representation).
PLEASE NOTE: In general, an API token has only a limited running time and must therefore be renewed after expiry. Normally, the standard running time is one month.
3. Checking a document
With the help of this API, Word and InDesign documents can be checked. The output of each call consists of exactly one result document. In order to simplify the generation of the required URLs, the API token administration offers an overview of all available configurations and also the corresponding REST URLs. In this URL, the correct API token is already included. After selecting the desired result type, the URL can simply be copied and inserted in your own system.
The available configurations for checking a document are listed chronologically with a grey background. By clicking on one of the configurations, the following details are provided: the description text for the individual configuration (Description), a dropdown list containing the possible types of result documents (Type) as well as the REST URL corresponding to the selected output format (see figure 4).
Figure 4: The details of the selected configuration (exemplary representation).
Depending on which result document is required (the commented version of the document, the XML version of the document, the XML check report or the formatted HTML check report), it has to be selected in the dropdown list next to »Type« (see figure 5).
Figure 5: Selecting the desired output format.
Further information on the available result documents after checking a document can be found under Checking a Word document - 3.2 The output documents for Word, under Checking an InDesign document - 3.2 The output documents as well as under The InDesign-to-EPUB Check - 2.2 The output documents for InDesign.
In order to check a document, a POST request in the format multipart/form-data
is sent to the corresponding URL.
The file to be checked must be attached as a parameter with the name file
. The processing is carried out synchronously, which means the request runs as long
as the check is completed and then returns the selected output format as a result.
Depending on the load of the data2check service, this process may take a few seconds.
Example: By using curl
, a Word document could be checked as follows:
curl -X POST -o result.docx -F file=@example.docx "http://service.data2check.de/api/doc/docx?wfid=CONFIGURATION-ID&tokenid=TOKEN"