The FAIR API

Overview

FAIR Data Services has been designed with an API-driven approach where all actions that can be performed in the user interface are possible by using the API.

The FAIR API is split into a number of sub-APIs:

• Search API: discover data.
• Datasets API: browse, create, update, and delete datasets.
• Requests API: browse, create and review data access requests.
• Files API: upload attachments to datasets
• Metrics API: obtain metrics from FAIR such as the number of datasets or searches performed.
• Role API: create and/or assign roles to users.
• Configuration Vocabulary API: add or modify links to external locations (e.g. Terms and Conditions)
• Other endpoints (such as selection) are in a beta phase.

API Documentation

The API documentation can be found at your FAIR instance’s /api/docs/ path. For example: https://fair.preview.aridhia.io/api/docs/.

The API is described using the OpenAPI v3 specification.

Authenticating against the API

FAIR users have two ways of authenticating against the FAIR API:

1. Create a long life token
2. Use a user access token

We recommend the first option, but both are detailed below.

Long Life Token - recommended

Data Stewards and Data Managers can generate a long life token via the FAIR UI by following the steps below:

Step 1. Select My API Tokens from the About FAIR menu

Step 2. Select Create New Token on the token management screen

Step 3. User will then have to define the token

• Name - the name of the token
• Role - the token's permissions are determined by its role. Users can select from existing token roles via this drop down. See below for more details.
• Valid to - date the token is valid to
• Only allow access from - if required, users can limit the IP addresses a token can be used from
• Single use token - token can be limited to a single use
• Reason - the reason the token was created

The user will then be presented with the token in a pop up, this should be copied to a secure store. Once the user closes the page or the session expires they will no longer be able to regenerate the token.

Token Roles

As with users accessing FAIR via the UI, the permissions granted to a token are dependent on its role. This role is assigned via the process detailed above. Users can create a custom role for a token by following the process detailed here.

Managing long life tokens

Users with the Administrator and Data Steward roles can manage the tokens of other users.

This can be done via the API Tokens option on the Administer menu. This opens a searchable list of all existing tokens. From here, administrative users can deactivate and expire any token.

Session Access token

Users can also authenticate against the API using a session access token. This can also be accessed from the About FAIR menu.

If users select the About option, they will be presented with the following:

This token can also be used to authenticate the API, but we do not recommend this, due to its short expiry time.

Examples

A number of example API calls using Python exist in our FAIR API examples repository. These examples cover searching for data, viewing dataset metadata, creating a dataset and uploading attachments.