API Usage

The FAIR Data Point exposes API endpoints that allow consumers to interact with the metadata. Some of the endpoints are available for all users, while others require an API token for authorization.

Obtaining an API token

In order to obtain an API token, you invoke the /tokens endpoint with your user credentials.

curl -X POST -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ "email": "user@example.com", "password": "secret" }' \
    https://fdp.example.com/tokens

A successful call will return a JSON object with a token.

{ "token": "efIobn394nvJJFJ30..." }

Issueing a request with the authorization token

Subsequent requests should use this token in the Authorization header. The authorization type is a Bearer token.

curl -H "Authorization: Bearer efIobn394nvJJFJ30..." \
    -H "Accept: application/json" https://fdp.example.com/users

Interacting with metadata

The metadata layers as defined by the Resource definitions are exposed through their respective endpoints. The general approach is that each layer, defined by its prefix, supports a number of read and write HTTP methods.

Method

URL pattern

Functionality

GET

/${prefix}/${uuid}

Retrieving metadata

POST

/${prefix}

Creating metadata

PUT

/${prefix}/${uuid}

Update metadata

Retrieving metadata

Retrieving metadata is open for GET requests without authorization. In the following example, we retrieve a Dataset resource by issuing a GET request to the /dataset prefix followed by its identifier (a UUID).

curl -H "Accept: text/turtle" https://fdp.example.com/dataset/58d7fbde-6c16-483e-b152-0f3ced131ca9

Creating metadata

New metadata can be created by POST-ing the content to the appropriate endpoint. First we will create a file called metadata.ttl to store our new metadata.

@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

<> a dcat:Dataset ;
    dct:title "test" ;
    dct:hasVersion "1.0" ;
    dct:publisher [ a foaf:Agent ; foaf:name "Example User" ] ;
    dcat:theme <http://www.wikidata.org/entity/Q14944328> ;
    dct:isPartOf <https://fdp.example.com/catalog/5f4a32c5-1f26-4657-9240-fc7ede7f1ce5> .

This metadata can be created by the following POST request.

curl -H "Authorization: Bearer efIobn394nvJJFJ30..." \
    -H "Content-Type: text/turtle" \
    -d @metadata.ttl https://fdp.example.com/dataset

When created, the metadata is initially in a DRAFT state. To publish the metadata using the API you can issue the following PUT request to transistion the metadata from the DRAFT state to the PUBLISHED state.

curl -X PUT -H "Authorization: Bearer efIobn394nvJJFJ30..." \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ "current": "PUBLISHED" }' \
    https://fdp.example.com/dataset/79508287-a2a7-4ae2-95b3-3f595e3088cc/meta/state

Update metadata

Existing metadata can be updated by issuing a PUT request with the request body being the updated metadata.

curl -X PUT -H "Authorization: Bearer efIobn394nvJJFJ30..." \
    -H "Content-Type: text/turtle" \
    -d @metadata.ttl https://fdp.example.com/dataset/79508287-a2a7-4ae2-95b3-3f595e3088cc

API endpoint listing

The available APIs are documented using OpenAPI. In the /swagger-ui.html endpoint the APIs are visualized through Swagger UI.