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

Retrieve a single record persisted in the Datahub database.

The identifier isn't an internally issued identifier (i.e. autoincrement). The Datahub will retrieve identifier from the record during ingest. Supported formats are defined as datatypes. Each datatype implements retrieval of the identifier from the raw data, based on an (opinionated) interpretation of the format specification.

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"
    }
  }
}

Adding a format extension will yield the same data in a different serialization format. The Datahub supports XML (.xml) and JSON (no extension or .json). The JSON format will yield a JSON serialization of the raw XML formatted data in Clark Notation. It's recommended to convert the JSON formatted input into an XML string before trying to extract data from the record (i.e. through XQuery or XPath).

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