Service Vocabulary API

Before using the API, ensure you are correctly setup to use the API (e.g. authentication) and have the appropriate permission to use the API. See the ‘FAIR API’ article for more information. The FAIR Service Vocabulary API provides the ability to (currently) customise links to external sources.

Prerequisites

In order to use the Service Vocabulary API, you need your FAIR user to have either:

• the 'Admin' role assigned to your user.
• a custom role with the vocabularies/update permission.
• see the article 'Configuring the Service Vocabularies' for information on current vocabularies

Vocabularies Codes

Vocabularies are pre-configured within FAIR and have default values. These values are then modified by the API to custom locations a user specifies. New vocabularies can be added by contacting Aridhia. The following vocabularies exist that are detailed below:

• Terms & conditions: t-and-c-link
• Aridhia DRE FAIR logo: portal-link
• External link dropdown: ** external-links-name: specifies the label of the dropdown. ** external-links: specifies the links within the dropdown.
• DRE name: dre-name
• DAR Request Email: request-access-email
• DAR Request Approved Email: request-approved-email
• DAR Request Denied Email: request-denied-email

Vocabulary Contents

Each vocabulary is specified in JSON and has the following attributes:

• id: an integer ID that can be used to reference the vocabulary when using the API.
• code: a code that can be used to reference the vocabulary when using the API.
• name: the name of the vocabulary.
• value: the current value/link that the vocabulary should point to.
• original: the default value/link that the vocabulary pointed to previously. Useful if a user needs to revert to the original value.
• created_at: when the vocabulary was created.
• updated_at: when the vocabulary was last updated including when the user made changed to ‘value’.

To modify a vocabulary, only the parameter ‘value’ is required to be changed (and can only be changed) to update a link. New vocabularies can be added by contacting Aridhia.

As an example, below is the default Terms and Conditions vocabulary.

{
   "id": 1,
   "code": "t-and-c-link",
   "name": "Terms and Conditions Link",
   "value": "/terms-and-conditions/",
   "original": "/terms-and-conditions/",
   "created_at": "2020-10-07T08:02:50.617Z",
   "updated_at": "2020-10-07T08:02:50.617Z"
}

Existing vocabularies can be obtained by issuing a GET request to the /vocabularies endpoint.

Updating a Vocabulary

In order to update a vocabulary, the following information needs to be obtained:

• The code of the vocabulary to modify (see above).
• The link (or series of links) the vocabulary should be updated to refer to.

To update a role, call the API with the following parameters:

• Request type: PUT
• Endpoint: /vocabularies/{code}
• Body: the body must include the value(s) the vocabulary should be updated to. An example is below.

#data.json
{
   "value": "https://www.aridhia.com"
}

Example API Call 1

Updating the ‘terms and conditions’ vocabulary to a ‘https://www.aridhia.com’ (with the body above):

curl -X PUT -d @data.json -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://fair.aridhia.io/api/vocabularies/t-and-c-link

Example API Call 2

In order to set the Custom Dropdown, the name and values must be set separately.

1. First the name is set by issuing a PUT to /vocabularies/external-links-name

{ 
   "value": "Workspaces"
}

1. Secondly the link values are set in an array by issuing a PUT to */vocabularies/external-link *

{
   "value": "[
      {\"name\": \"Europe\", \"href\": \"https://workspaces.europe.aridhia.io\" },
      {\"name\": \"UK\", \"href\": \"https://workspaces.uk.aridhia.io\" },
      {\"name\": \"US\", \"href\": \"https://workspaces.us.aridhia.io\" }
   ]"
}