General documentation

To use our APIs, you can use the documentation provided if you ever need help and advice for your own implementation. In this general part, let's talk about server authentication, the API key and possible errors.

Access methods

The following methods, which map a corresponding CRUD operation, support access to the individual entities:

• GET - Reading the data records with the appropriate filter or determining all authorized data records
• POST - Create a new data record
• PUT - Update the transferred data record
• DELETE - Delete the data record with the transferred key

Calling entities

Many entities will say that you need an API key to use the API. You can easily create and manage this with an account on our website. You have to add the key to the request's header when you call it.

Entities that require authentication must be called with the corresponding token in the header. This token must have been generated beforehand via the "API: Users" and has a corresponding shelf life.

Header

In some cases, appropriate information must be stored in the request header so that the API accepts the request. The following information can be given:

• "Content-Type: application/json" (our interfaces only work in JSON format)
• "Authorization: Bearer [TOKEN]" (Transfer of the security token to verify the user on the server)
• "Swh-API-Key: [API-KEY]" (API-Key for the interface to verify the usage)

Filter

In the case of requests, the data can be restricted to the corresponding nodes using a filter. The three key fields "NODE_ID", "PARENT_ID" and "ROOT_ID" are used for this access. Entities and actions for which a filter is allowed are marked with [/ FILTER]. Some examples for the use of the filter:

• /projects/(NODE_ID=XYZ)
• /workspace/(ROOT_ID=XYZ,PARENT_ID=ABC)

Metadata

With the addition $metadata you can call up the metadata of the service and thus access further information on the tables, fields and data types. The corresponding path is also given for each table.