Use the API
Dataland uses the OpenAPI specification and tools build on top of it (e.g. Swagger) to document the API. In the following it is assumed that you are familiar with the approach.
When interacting with the Dataland API the most convenient way to authenticate is by using an API key. The key is used as a bearer token. To generate it simply do the following:
- Log in to the website of the dataland service you want to interact with (either dataland.com or test.dataland.com)
- In the top right corner, open the user menu and select "API KEY". A redirect will occur and open the API key page.
- Follow the instructions displayed on the site to obtain an API key.
After creation of the API key, various batches show what rights are associated with the API key (see example below).
The badges are connected to the reader, uploader and reviewer role in dataland. By default a user account only has the reader role. To request the uploader or reviewer role reach out to the dataland inbox ([email protected]).
Please note: The rights of the API key, reflect your roles at the time of creation. If new roles were added later, regenerate the API key to include them. In case you are experiencing unexpected authenitaction issues, double check the roles associated to your API key on the website.
There are currently three outward facing APIs. The json representation can be found here:
- https://github.com/d-fine/Dataland/blob/main/dataland-backend/backendOpenApi.json
- https://github.com/d-fine/Dataland/blob/main/dataland-document-manager/documentManagerOpenApi.json
- https://github.com/d-fine/Dataland/blob/main/dataland-qa-service/qaServiceOpenApi.json
The first one deals with the general exchange of data and is relevant for up- and downloading. The second one exclusively deals with the up- and download of documents. The third is only required for users in the reviewer role that want to QA data.
To experiment and explore the API hands on, use the Swagger UIs available under:
- https://test.dataland.com/api/swagger-ui/index.html (dataland-backend)
- https://test.dataland.com/documents/swagger-ui/index.html (dataland-document-manager)
- https://test.dataland.com/qa/swagger-ui/index.html (dataland-qa-service)
In case unexpected behavior occurs or it is not clear how to use certain features, reach out to the technical support available under [email protected].