usage.html

---
layout: default
title: Datahub installation
permalink: /datahub/usage
---

<div class="subtron text-center">
	<div class="container-narrow">
		<h1>The Datahub Documentation</h1>

		<p class="docs-breadcrumbs">
			<a href="/datahub">Introduction</a> /
			<a href="/datahub/installation">Installation</a> /
			<a href="/datahub/usage">Usage</a>
		</p>

	</div>
</div>

<section class="page-section strong-headers">
	<div class="container-narrow">

	<h1>Usage</h1>

	<h2>The REST API</h2>

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

	<h3>POST and PUT actions</h3>

	<p>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.</p>

	<p>A valid POST HTTP request looks like this:</p>

	{% highlight xml %}
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>
...
{% endhighlight %}

	<h3>GET actions</h3>

	<p>Sending a GET HTTP request to the <code>api/v1/data</code> 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 <a href="https://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a> constraint.</p>

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

	{% highlight bash %}
GET api/v1/data               # only JSON supported
GET api/v1/data/objectPID     # return JSON
GET api/v1/data/objectPID.xml # return XML
	{% endhighlight %}

	<h2>The OAI-PMH endpoint</h2>

	<p>The datahub supports the <a href="https://www.openarchives.org/pmh/">OAI-PMH</a> protocol. The endpoint is available via the <code>/oai</code> path.</p>

	{% highlight bash %}
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
	{% endhighlight %}

	<p>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.</p>

	<h2>Access control via OAuth</h2>

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

	{% highlight bash %}
# 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]
    {% endhighlight %}

<p>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:</p>

	{% highlight bash %}
curl 'http://localhost:8000/oauth/v2/token?grant_type=password&username=admin&password=datahub&client_id=slightlylesssecretpublicid&client_secret=supersecretsecretphrase'
    {% endhighlight %}

	<p>Example output:</p>

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

    <p>The endpoint can also be used to revoke both access and refresh tokens.</p>

	{% highlight bash %}
 curl 'http://localhost:8000/oauth/v2/revoke?token=ZDIyMGFiZGZkZWUzY2FjMmY4YzNmYjU0ODZmYmQ2ZGM0NjZiZjBhM2Q0Y2ZjMGNiMjc0ZWIyMmYyODMzMGJjZg'
    {% endhighlight %}

    <p>Example output:</p>
	{% highlight json %}
{
    "result": "success",
    "message": "The token has been revoked."
}
    {% endhighlight %}

	<h2>The Dashboard</h2>

	<p>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.</p>

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

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

	<h2>Administration</h2>

	<h3>Logging in</h3>

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

	<p>You need to manually change the password to secure your installation.</p>

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

	<h3>Managing users</h3>

	<p>To be written.</p>

	<h3>Managing clients</h3>

	<p>To be written.</p>


	</div>
</section>