Usage

The REST API

The REST API is available at api/v1/data. Documentation about the available API methods can be found at /docs/api.

POST and PUT actions

The PUT and POST actions expect and XML formatted body in the HTTP request. The Content-Type HTTP request header also needs to be set accordingly. Currently, supported: application/lido+xml. Finally, you will need to add a valid OAuth token via the access_token query parameter.

A valid POST HTTP request looks like this:

POST /api/v1/data?access_token=MThmYWMxMjFlZWZmYjVmZDU2NDNmZWIzYTE0YmNiYTk3YTc5ODJmMWJjOGI1MjE5MWY4ZjEyZWZlZmM2ZmZmNg HTTP/1.1
Host: example.org
Content-Type: application/lido+xml
Cache-Control: no-cache

<?xml version="1.0" encoding="UTF-8"?>
<lido:lido xmlns:lido="http://www.lido-schema.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.lido-schema.org http://www.lido-schema.org/schema/v1.0/lido-v1.0.xsd">
	<lido:lidoRecID lido:source="Deutsches Dokumentationszentrum für Kunstgeschichte - Bildarchiv Foto Marburg" lido:type="local">DE-Mb112/lido-obj00154983</lido:lidoRecID>
	<lido:category>
...

GET actions

Sending a GET HTTP request to the api/v1/data endpoint will return a paginated list of all the records available in the API. The endpoint will return a HTTP response with a JSON formatted body. The endpoint respects the HATEOAS constraint.

Content negotation is currently only supported via a file extension on individual resource URL's.

GET api/v1/data               # only JSON supported
GET api/v1/data/objectPID     # return JSON
GET api/v1/data/objectPID.xml # return XML

The OAI-PMH endpoint

The datahub supports the OAI-PMH protocol. The endpoint is available via the /oai path.

GET oai/?metadataPrefix=oai_lido&verb=ListIdentifiers
GET oai/?metadataPrefix=oai_lido&verb=ListRecords
GET oai/?metadataPrefix=oai_lid&verb=GetRecord&identifier=objectPID
GET oai/?metadataPrefix=oai_lid&verb=GetRecord&identifier=objectPID
GET oai/?metadataPrefix=oai_lido&verb=ListIdentifiers&from=2017-06-29T05:22:30Z&until=2017-07-14T04:22:30Z

The datahub doesn't implement grouping of records nor soft deletes. As such, the OAI endpoint doesn't OAI sets and indicating whether a record has been deleted.

Access control via OAuth

The datahub API can be set up to be either a public or a private API. The public_api_method_access parameter in the parameters.yml configuration file allows you to configure which parts of the API are public or private:

# Setting this to some unknown value like [FOO] disables public api access
# Leaving this option empty [] means allowing all methods for anonymous access
# public_api_method_access: [FOO]
public_api_method_access: [GET]

The datahub requires OAuth authentication to ingest or retrieve metadata records. The administrator has to issue a user account with a client_id and a client_secret to individual Users or client applications. Before clients can access the API, they have to request an access token:

curl 'http://localhost:8000/oauth/v2/token?grant_type=password&username=admin&password=datahub&client_id=slightlylesssecretpublicid&client_secret=supersecretsecretphrase'

Example output:

{
    "access_token": "ZDIyMGFiZGZkZWUzY2FjMmY4YzNmYjU0ODZmYmQ2ZGM0NjZiZjBhM2Q0Y2ZjMGNiMjc0ZWIyMmYyODMzMGJjZg",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": "internal web external",
    "refresh_token":  "MzhkYzY0MzMxM2FmNmQyODhiOWM4YzEzZjI3YzViZjg3ZThlMTA2YWY4ZTc2YjUwYzgxNzVhNTlmYTBkYWZhNQ"
}

The endpoint can also be used to revoke both access and refresh tokens.

 curl 'http://localhost:8000/oauth/v2/revoke?token=ZDIyMGFiZGZkZWUzY2FjMmY4YzNmYjU0ODZmYmQ2ZGM0NjZiZjBhM2Q0Y2ZjMGNiMjc0ZWIyMmYyODMzMGJjZg'

Example output:

{
    "result": "success",
    "message": "The token has been revoked."
}

The Dashboard

When you surf to your Datahub installation, you will land on the Dashboard of the application. The Dashboard displays the number of records currently stored in the installation and links to the technical documentation of the API's.

A Datahub installation has a name which is prominently featured on the Dashboard and can be configured in app/config/parameters.yml.

The Dashboard also displays a link to the website of the organisation or individual who manages the installation and a contact e-mail address.

Administration

Logging in

During installation, a 'administrator' user was created with the username admin and the default password datahub. When you surf to /login, you will be presented with a login form. Use these default credentials as you log in for the first time.

You need to manually change the password to secure your installation.

Click on the 'Users' link in the main menu
Click on the 'Users' link in the 'Navigation' sidebar.
A table of registered users with just the 'admin' entry is displayed.
Click on the 'view' action button in the 'admin' entry row.
The account details of the admin user are now displays.
Click on the 'Edit' button to edit the account.
Enter a new password to change the password.
Click on 'submit' to save the new passowrd.

Managing users

To be written.

Managing clients