05. REST API v2

Overview

This section describes the resources that make up the REST API of the Datahub v2.0.0 and higher.

Versioning

The Datahub 2.0.0 and higher currently doesn't support API versioning.

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
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 sent and received as JSON by default. The API sends and receives metadata records in various XML formats. Content negotiation is supported through the HTTP headers Accept and Content-Type. The API adheres to IANA registered Media Types as close as possible.

These Media Types are supported:

application/json
application/xml
application/rdf+xml
application/lido+xml
application/mods+xml
application/marcxml+xml

If no Accept header is present, the API will sent JSON by default.

Sets

List all sets

GET /api/sets

Get a single set

GET /api/set/:set

Create a new set

PUT /api/set/:set

Update an existing set

PUT /api/set/:set

Delete an existing set

DELETE /api/set/:set

List all the records in a single set

GET /api/set/:set/items

Update a list of existing records associated with a single set

PUT /api/set/:set/items

Remove all the reocrds from a single set

DELETE /api/set/:set/items

Records

List all the records

GET /api/items

Get a single record

GET /api/item/:oai-identifier

Create a new record

PUT /api/item/:oai-identifier

Update an existing record

PUT /api/item/:oai-identifier

Delete an existing record

DELETE /api/item/:oai-identifier