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
URLs an einer URN abfragen
Eigene URLs an einer URN abfragen
Einzelne URL abfragen
Hinzufügen einer URL zu einer URN
Löschen einer URL von einer URN
Aktualisieren der Priorität einer URL
Austauschen aller eigenen URLs an einer URN