04. REST API v1

Overview

This section describes the resources that make up the REST API of the Datahub v1.x.

Versioning

The REST API is versioned through the URI schema: api/v1

Schema

Preferably, HTTPS is used for all API access. The API is accessed directly from the /api base url of your installation: https://organisation.org/api. All data is sent and received as JSON by default, unless Accept and Content-Type headers indicate otherwise through supported Media Types.

foo@bar:~$ curl -i https://organisation.org/api/v1/data
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Connection: keep-alive
X-Powered-By: PHP/7.0.33-1+ubuntu14.04.1+deb.sury.org+1
Date: Thu, 07 Feb 2019 02:09:37 GMT

Authentication

Requests that require authentication will return 403 Forbidden. In some places, 404 Not Found is returned. This is to prevent the accidental leakage of private information to unauthorized users.

OAuth

...

Media Types

All data is received by clients as JSON by default. The API only accepts metadata records in LIDO XML format. Content negotiation is supported through the HTTP header Content-Type when when performing a POST or PUT. Clients receive data in their preferred format through an optional extension in the URI (.xml or .lidoxml).

These Media Types are supported:

applicaiton/hal+json
application/lido+xml

The REST API support HATEOAS (Hypertext As The Engine Of Application State) through HAL (Hypertext Application Language). HATEOAS compliant HTTP clients will be able to crawl through the API by discovering HAL compliant hyperlinks when sending HTTP GET requests.

Records

List all the records

Lists all the records currently persisted in the Datahub database.

GET /api/v1/data

Parameters

Name	Type	Description
limit	int	Number of records to retrieve (default: 5)
offset	int	The offset from where to start (default: 0)

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "offset": 0,
  "limit": 5,
  "total": 15852,
  "_links": {
    "self": {
      "href": "/api/v1/data?limit=5"
    },
    "first": {
      "href": "/api/v1/data?limit=5"
    },
    "last": {
      "href": "/api/v1/data?offset=15850&limit=5"
    },
    "next": {
      "href": "/api/v1/data?offset=5&limit=5"
    }
  },
  "_embedded": {
    "records": [
      {
        "id": "5b8fe262c8913d0c4932fc79",
        "created": "2018-09-05T16:04:18+02:00",
        "updated": "2018-10-23T13:38:34+02:00",
        "json": [
          {
            "name": "{http://www.lido-schema.org}lidoRecID",
            "value": "0000_ABC1561_D",
            "attributes": {
              "{http://www.lido-schema.org}pref": "alternate",
              "{http://www.lido-schema.org}type": "purl",
              "{http://www.lido-schema.org}source": "Museum Name",
              "{http://www.lido-schema.org}label": "dataPID"
            }
          },
          {
            "name": "{http://www.lido-schema.org}lidoRecID",
            "value": "oai:museum.org:0000_ABC1561_D",
            "attributes": {
              "{http://www.lido-schema.org}pref": "preferred",
              "{http://www.lido-schema.org}type": "urn",
              "{http://www.lido-schema.org}source": "Museum name",
              "{http://www.lido-schema.org}label": "dataPID"
            }
          },
        ]
     },
    ]
  }
}

Get a single record

GET /api/v1/data/:identifier{.:format}

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "json": [
    {
      "name": "{http://www.lido-schema.org}lidoRecID",
      "value": "http://groeningemuseum.be/collection/work/data/0000_GRO1561_I",
      "attributes": {
        "{http://www.lido-schema.org}pref": "alternate",
        "{http://www.lido-schema.org}type": "purl",
        "{http://www.lido-schema.org}source": "Musea Brugge - Groeningemuseum",
        "{http://www.lido-schema.org}label": "dataPID"
      }
    },
    {
      "name": "{http://www.lido-schema.org}lidoRecID",
      "value": "oai:datahub.vlaamsekunstcollectie.be:groeningemuseum.be:0000_GRO1561_I",
      "attributes": {
        "{http://www.lido-schema.org}pref": "preferred",
        "{http://www.lido-schema.org}type": "urn",
        "{http://www.lido-schema.org}source": "Vlaamse Kunstcollectie - Arthub Flanders",
        "{http://www.lido-schema.org}label": "dataPID"
      }
    },
    {
      "name": "{http://www.lido-schema.org}objectPublishedID",
      "value": "http://groeningemuseum.be/collection/work/id/0000_GRO1561_I",
      "attributes": {
        "{http://www.lido-schema.org}type": "purl",
        "{http://www.lido-schema.org}source": "Musea Brugge - Groeningemuseum",
        "{http://www.lido-schema.org}label": "workPID"
      }
    },
  ],
  "_links": {
    "self": {
      "href": "/api/v1/data/oai%3Adatahub.vlaamsekunstcollectie.be%3Agroeningemuseum.be%3A0000_GRO1561_I"
    }
  }
}

Create a new record

POST /api/v1/data

Create a new record or update an existing record

PUT /api/v1/data/:identifier

Delete an existing record

DELETE /api/v1/data/:identifier