REST API Overview

This section contains general REST API information as well as app specific REST API reference. Unless otherwise stated, general principles apply to all REST API endpoints regardless of application.

For developing REST API views for your own SODAR Core based apps, see REST API Development.

Model Access and Permissions

In SODAR Core REST API views, objects are accessed through their sodar_uuid field. In the API documentation, “UUID” stands for this field unless otherwise noted. For most endpoints, you are expected to provide the UUID at the end of the URL to specify the object you are trying to access. Examples:

/project/api/retrieve/67eeba1e-3743-4b58-ad43-5f92e9faf426
/files/api/file/retrieve-update-destroy//bf5c9467-7e50-4087-8f90-699762f45150

For permissions, the REST API uses the same rules which are in effect in the SODAR Core GUI. That means you need to have appropriate project access for each operation. Conversely, if you already have a certain level of access to a project in the GUI, the same operations are available to you in the REST API without the need to acquire extra permissions.

Authentication

The API supports authentication through Knox authentication tokens, as well as logging in using your SODAR username and password. Tokens are the recommended method for security purposes.

For token access, first retrieve your token using the Tokens App. Add the token in the Authorization header of your HTTP request as follows:

Authorization: token 90c2483172515bc8f6d52fd608e5031db3fcdc06d5a83b24bec1688f39b72bcd

Using the Python requests API, this would be set up as follows:

api_token = 'YOUR-API-TOKEN-HERE'
auth_header = {'Authorization': f'token {api_token}'}

Versioning

The SODAR Core REST API uses accept header versioning. While specifying the desired API version in your HTTP requests is optional, it is strongly recommended. This ensures you will get the appropriate return data and avoid running into unexpected incompatibility issues.

Each application is expected to use its own media type and version numbering. To enable versioning, add the Accept header to your request with the app’s respective media type and version number. Example for the projectroles API:

Accept: application/vnd.bihealth.sodar-core.projectroles+json; version=x.y

In Python requests, this would be formed as follows:

accept_header = {'Accept': 'application/vnd.bihealth.sodar-core.projectroles+json; version=x.y'}

SODAR Core REST APIs must conform to semantic versioning. Breaking changes require a major 1.* update, while non-breaking new features can be tagged with a minor *.1. Patch updates should be reserved for bug fixes.

APIs should be kept backwards compatible as feasible, with support for previous versions maintained and ensured in API view tests.

Removing support for old API versions should be done by announcing them as deprecated in a major SODAR Core version *.1.* or greater (see SODAR Core Versioning), followed by removing support in the next major version.

Request Data

Data provided to POST, PUT or PATCH requests should be JSON encoded unless otherwise specified. Using Python requests, this can be done by providing a Python dictionary in the request json parameter. Example:

sodar_url = 'https://your.sodar.core.instance'
url = f'{sodar_url}/project/api/create'
data = {
    'title': 'New Project via API',
    'type': 'PROJECT',
    'parent': category_uuid,
    'owner': user_uuid
}
headers = {}  # Auth and accept headers here
response = requests.post(url, json=data, headers=headers).json()

Return Data

The return data for each request will be a JSON document unless otherwise specified.

If return data is not specified in the documentation of an API view, it will return the appropriate HTTP status code along with an optional detail JSON field upon a successfully processed request.

For creation views, the sodar_uuid of the created object is returned along with other object fields.

Pagination

List views support pagination unless otherwise specified. Pagination can be enabled by providing the ?page=x query string in the API request. This will change the return data into a paginated format. Example:

{
    'count' 170,
    'next': 'api/url?page=3',
    'previous': 'api/url?page=1',
    'results': [
        # ...
    ]
}