Diese Seite zeigt Beispiele für typische Aktivitäten bei der Verwaltung von URNs über die REST-API.
Information zu Namensraum anzeigen
Ü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
Abfragen eines Vorschlags für eine URN
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
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.
Registrieren einer neuen URN
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 } ] }
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.
Existenzprüfung für eine URN
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
Wenn sie nicht existiert, wird der Status 404 Not Found
zurückgegeben:
HEAD /sandbox/v2/urns/urn/urn:nbn:de:example-nicht-registriert
URN abfragen
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
URLs an einer URN abfragen
Ü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
Eigene URLs an einer URN abfragen
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
Da nur eine URL zu unserer Beispiel-URN registriert ist, erhalten wir dieselbe Liste wie bei der Abfrage aller URLs.
Einzelne URL abfragen
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
Hinzufügen einer URL zu einer URN
Um eine zusätzliche URL zu einer URN zu registrieren, kann ein POST
-Request auf den Endpunkt /urns/urn/<urn>/urls
gemacht werden. Zusätzliche URLs dürfen nicht nur an eigenen URNs registriert werden, sondern an beliebigen URNs. Die Angabe des Feldes priority
ist wieder optional.
POST /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Content-Type: application/json Accept: application/json { "url" : "http://example.org/another-document-url", "priority" : 100 }
Als Antwort auf das Anlegen einer neuen URL wird der Status 201 Created
zurückgegeben und die Beschreibung der neuen URL zurückgegeben.
Aktualisieren der Priorität einer URL
Um die Priorität einer URL zu ändern, kann ein PATCH
-Request auf die jeweilige URL-Ressource unter dem Endpunkt-Muster /urns/urn/<urn>/urls/base64/<url-in-base64>
gemacht werden.
PATCH /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2Fub3RoZXItZG9jdW1lbnQtdXJs Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Content-Type: application/json Accept: application/json { "priority" : 3 }
Wenn die Änderung der Priorität erfolgreich durchgeführt wurde, liefert die API den Status 204 No Content
zurück.
Löschen einer URL von einer URN
Soll eine URL von einer URN gelöscht werden, so geschieht dies über einen DELETE
-Request auf die URL-Referenz /urns/urn/<urn>/urls/base64/<url-in-base64>
. Dabei können selbstverständlich nur die eigenen URLs gelöscht werden. Außerdem muss mindestens eine URL an der URN registriert bleiben. Wenn die eigene die letzte URL an einer URN ist, kann sie nicht entfernt werden.
DELETE /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/urls/base64/aHR0cDovL2V4YW1wbGUub3JnL2Fub3RoZXItZG9jdW1lbnQtdXJs Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Accept: application/json
Das erfolgreiche Löschen wir durch den Status 204 No Content
zurückgemeldet.
Austauschen aller eigenen URLs an einer URN
Neben dem Hinzufügen und Löschen einzelner URLs bietet die URN-Service API auch die Möglichkeit, alle eigenen URLs durch neue URLs zu ersetzen. Dies geschieht über einen PATCH
-Request an den Endpunkt /urns/urn/<urn>/my-urls
. Der Request muss eine Liste der neuen URLs enthalten. Diese können sich auch teilweise mit den Existierenden überschneiden, falls nur ein Teil der URLs verändert werden soll. Im folgenden Beispiel, soll die existierende URL beibehalten werden, daher ist sie in der Liste enthalten. Allerdings verändern wir ihre Priorität. Zusätzlich registrieren wir eine neue URL. Dabei verzichten wir auf die Angabe der Priorität, sodass die URL die Priorität 0 erhält.
PATCH /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532/my-urls Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Content-Type: application/json Accept: application/json [ { "url": "http://example.org/document-url", "priority": 23 }, { "url": "http://example.org/additional-document-url" } ]
Nachfolger einer URN setzen
In seltenen Fällen kann es vorkommen, dass eine URN durch eine Nachfolge-URN ersetzt werden soll. Beim Resolving soll dann automatisch von der alten URN zum Nachfolger weitergeleitet werden. URN-Besitzer können diese Nachfolger-Beziehung einrichten. Dies geschieht über einen PATCH
-Request auf due URN-Ressource /urns/urn/<urn>
. Die Nachfolger-URN wird über ihren kanonischen API-Referenz identifiziert, der im @id
-Feld jeder URN enthalten ist:
PATCH /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532 Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Content-Type: application/json Accept: application/json { "successor": "https://api.nbn-resolving.org/sandbox/v2/urns/urn/urn:nbn:de:example-20190213151552346346245" }
Das erfolgreiche Setzen der Nachfolge-URN wird mit dem Status 204 No Content
quittiert.
Nachfolger einer URN entfernen
Falls ein Nachfolge-URN fälscherlicher Weise gesetzt wurde, kann sie einfach wieder entfernt werden, indem ein PATCH
-Request mit einem null
-Wert als Nachfolger gesendet wird:
PATCH /sandbox/v2/urns/urn/urn:nbn:de:example-2019021315155244513532 Authorization: Basic dXJuLXBhcnRuZXI6bWVpbi1wYXNzd29ydA== Content-Type: application/json Accept: application/json { "successor": null }
Das erfolgreiche Löschen der Nachfolge-URN wird mit dem Status 204 No Content
bestätigt.