The FAIR API
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.
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:
- Create a long life token
- 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.
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.
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.