Diese Seite zeigt Beispiele für typische Aktivitäten bei der Verwaltung von URNs über die REST-API.
Über den Endpunkt /namespaces/name/<namensraum-name> können Informationen über einen Namensraum sowie URLs zu weiterführenden Ressourcen zu dem Namensraum abgefragt werden:
GET /sandbox/v2/namespaces/name/urn:nbn:de:example Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 656
Date: Wed, 13 Feb 2019 14:10:41 GMT
{
"name": "urn:nbn:de:example",
"creationDate": "2019-02-13T15:08:55+0100",
"lastModified": "2019-02-13T15:08:55+0100",
"allowsRegistration": true,
"organisation": "https://api.nbn-resolving.org/sandbox/v2/organisations/id/1",
"urnNamingPolicy": "https://api.nbn-resolving.org/sandbox/v2/policies/urn-naming/id/no-check",
"urlPolicy": "https://api.nbn-resolving.org/sandbox/v2/policies/url/id/no-check",
"comment": null,
"resolverUrl": "",
"urns": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example/urns",
"urnSuggestion": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example/urn-suggestion",
"@id": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example"
} |
Der URN-Service kann Vorschläge für neue URNs in einem Namensraum machen. Er garantiert, dass die URN zum Zeitpunkt der Anfrage noch nicht registriert ist und dass derselbe Vorschlag nicht zweimal gemacht wird. Die Funktion generiert nur einen Vorschlag es findet keine Registrierung oder Speicherung der URN statt. Nur der Besitzer des Namensraums kann sich Vorschläge für URNs in seinem Namensraum generieren lassen.
Ein URN-Vorschlag wird mit einem GET-Request auf die Ressource /namespaces/name/<namensraum-name>/urn-suggestion abgefragt:
GET /sandbox/v2/namespaces/name/urn:nbn:de:example/urn-suggestion Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 233
Date: Wed, 13 Feb 2019 14:15:52 GMT
{
"suggestedUrn": "urn:nbn:de:example-2019021315155244513532",
"namespace": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example",
"@id": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example/urn-suggestion"
} |
Das Feld suggestedUrn enthält einen Vorschlag für eine URN, die in dem Namensraum, auf den das Feld namespace verweist, registriert werden kann. Wie das geht ist im nächsten Schritt beschrieben.
URNs werden per POST-Request auf die Ressource /urns angelegt. Bei der Registrierung der URN muss mindestens eine URL angegeben werden. Außerdem müssen die Bedingungen des URN-Naming-Policy und der URL-Policy für den Namensraum erfüllt sein.
Die Angabe der priority ist optional. Sie bestimmt bei mehreren URLs in welcher Reihenfolge sie beim Resolving berücksichtigt werden. URLs mit höherer Priorität (d.h einer größeren Zahl) werden vorrangig verwendet (Hinweis: Dies ist im aktuellen NBN-Resolver auf https://nbn-resolving.org/ noch nicht vollständig umgesetzt).
POST /sandbox/v2/urns
Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA==
Content-Type: application/json
Accept: application/json
{
"urn": "urn:nbn:de:example-2019021315155244513532",
"urls": [
{
"url": "http://example.org/document-url",
"priority": 10
}
]
} |
HTTP/1.1 201 Created
Connection: keep-alive
Location: http://localhost:8080/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532
Content-Type: application/json
Content-Length: 527
Date: Wed, 13 Feb 2019 14:32:48 GMT
{
"urn": "urn:nbn:de:example-2019021315155244513532",
"creationDate": "2019-02-13T15:32:48+0100",
"lastModified": "2019-02-13T15:32:48+0100",
"namespace": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example",
"successor": null,
"urls": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls",
"myUrls": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/my-urls",
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532"
} |
Als Antwort auf das Anlegen einer neuen URN wird der Status 201 Created zurückgegeben und die Beschreibung der neuen URN zurückgegeben.
Mithilfe der URLs in den Feldern @id, urls, myUrls können wir jetzt leicht weitere Abfragen auf der URN vornehmen.
Um zu Überprüfen, ob eine URN registriert wurde, können wir einfach einen HEAD-Request auf den Endpunkt /urns/urn/<urn> machen. Wenn die URN existiert, wird der Status 200 OK zurückgegeben:
HEAD /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532 |
HTTP/1.1 200 OK Connection: keep-alive Content-Length: 0 Date: Wed, 13 Feb 2019 14:42:54 GMT <Response body is empty> |
Wenn sie nicht existiert, wird der Status 404 Not Found zurückgegeben:
HEAD /sandbox/v2/urns/urn/urn:nbn:de:example-nicht-registriert |
HTTP/1.1 404 Not Found Connection: keep-alive Content-Type: application/json Content-Length: 67 Date: Wed, 13 Feb 2019 14:44:45 GMT <Response body is empty> |
Statt nur die Existenz einer URN über die API zu erfragen, können per GET-Request auf den Endpunkt /urns/urn/<urn> auch Informationen zu einer registrierten URN abgefragt werden.
GET /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532 Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 527
Date: Wed, 13 Feb 2019 14:50:27 GMT
{
"urn": "urn:nbn:de:example-2019021315155244513532",
"creationDate": "2019-02-13T15:32:48+0100",
"lastModified": "2019-02-13T15:32:48+0100",
"namespace": "https://api.nbn-resolving.org/sandbox/v2/namespaces/name/urn:nbn:de:example",
"successor": null,
"urls": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls",
"myUrls": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/my-urls",
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532"
} |
Über den Link im Feld urls, dass wir bei der URN-Abfrage erhalten haben, können wir uns eine Liste aller URLs ausgeben lassen, die für die URN registriert sind:
GET /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 573
Date: Wed, 13 Feb 2019 14:53:08 GMT
{
"totalItems": 1,
"items": [
{
"url": "http://example.org/document-url",
"creationDate": "2019-02-13T15:32:48+0100",
"lastModified": "2019-02-13T15:32:48+0100",
"urn": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532",
"organisation": "https://api.nbn-resolving.org/sandbox/v2/organisations/id/1",
"priority": 10,
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2RvY3VtZW50LXVybA=="
}
],
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls"
} |
Statt alle registrierten URLs abzufragen, können wir auch den Link aus dem Feld myUrls aus der URN-Abfrage verwenden, um nur die URLs aufzulisten die uns gehören. Dies funktioniert natürlich nur, wenn wir Authentizierungsdaten in der Anfrage mitsenden. Die Liste ist entsprechend der Priorität unserer URLs sortiert. Falls wir keine URLs an einer URN registriert haben, bekommen wir eine leere Liste zurück.
GET /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/my-urls Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 576
Date: Wed, 13 Feb 2019 14:56:02 GMT
{
"totalItems": 1,
"items": [
{
"url": "http://example.org/document-url",
"creationDate": "2019-02-13T15:32:48+0100",
"lastModified": "2019-02-13T15:32:48+0100",
"urn": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532",
"organisation": "https://api.nbn-resolving.org/sandbox/v2/organisations/id/1",
"priority": 10,
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2RvY3VtZW50LXVybA=="
}
],
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/my-urls"
} |
Da nur eine URL zu unserer Beispiel-URN registriert ist, erhalten wir dieselbe Liste wie bei der Abfrage aller URLs.
Statt alle URLs an einer URN abzufragen, können wir auch gezielt eine einzelne URL abfragen. Dazu kann ein GET-Request auf den Endpunkt /urns/urn/<urn>/urls/base64/<url-in-base64> gemacht werden. Da eine URL nicht einfach als Teil einer anderen URL verwendet werden kann, muss die URL im Format Base 64 kodiert werden.
GET sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2RvY3VtZW50LXVybA== Accept: application/json |
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 449
Date: Wed, 13 Feb 2019 15:01:21 GMT
{
"url": "http://example.org/document-url",
"creationDate": "2019-02-13T15:32:48+0100",
"lastModified": "2019-02-13T15:32:48+0100",
"urn": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532",
"organisation": "https://api.nbn-resolving.org/sandbox/v2/organisations/id/1",
"priority": 10,
"@id": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2RvY3VtZW50LXVybA=="
} |