...
Die URN-Service API ist unter der Basis-Adresse https://api.nbn-resolving.org/ zu erreichen.
Die API ist versioniert, um bei inkompatiblen Veränderungen zeitweise mehrere Versionen der API betreiben zu können. Die Versionierung erfolgt über das Anhängen der API-Version an die Basis-Adresse. Die derzeit aktuelle Version ist v2:
...
Die Sandbox-API des URN-Service ist unter der Basis-Adresse https://api.nbn-resolving.org/sandbox/ zu erreichen. Die Versionierung erfolgt wie oben beschrieben. Die vollständige Basis-Adresse der Sandbox-API inklusive Versionsnummer lautet:
...
Die URN-Service API strebt eine korrekte Nutzung der HTTP-Verben an.
| HTTP-Verb | Beschreibung |
|---|---|
HEAD | Wird benutzt, um nur die HTTP-Header für eine Ressource abzufragen |
GET | Wird für das Abfragen von Ressourcen genutzt |
POST | Wird benutzt, um neue Ressourcen anzulegen |
PATCH | Wird verwendet, um Ressourcen mit partiellen JSON-Objekten zu aktualisieren |
PUT | Wird aktuell nicht von der REST-API verwendet |
DELETE | Wird benutzt, um Ressourcen zu löschen |
Fehler
Wenn eine Anfrage an die URN-Service API fehlschlägt, enthält die Antwort ein JSON-Objekt mit einer genaueren Fehlermeldung:
...
Einige Anfragen begrenzen die Menge an zurückgelieferten Elemente und paginieren die Ergebnisliste. Um durch die Ergebnisliste zu blättern, kann der Query-Parameter offset angeben werden. Dieser gibt an, mit welchem Element die Liste beginnen soll. Die Zählung beginnt bei 0. Wenn der Parameter nicht angegeben wird, wird mit dem ersten Element begonnen. Die Seitengröße kann mit dem Parameter count beeinflusst werden. Standardmäßig werden 20 Elemente ausgegeben.
Link-Header
Zum vereinfachten Blättern durch die Ergebnislisten, enthalten die Antworten der URN-Service API einen HTTP Link-Header, der Links zur ersten, vorhergehenden, folgenden und zur letzten Seite enthält. Links zur ersten Seite und zur Vorgängerseite sind erst ab der zweiten Seite enthalten. Der Link auf die letzte Seite ist optional und aus technischen Gründen nicht immer enthalten.
...
Eine detaillierte Übersicht über alle Befehle der REST-API wird als Teil der REST-API unter docs/index.html angeboten.
Beispiele:
Diese Seite zeigt Beispiele für typische Aktivitäten bei der Verwaltung von URNs über die REST-API.
Java-Client
Besteht Interesse, die eigene (Java-)Anwendung an die URN-Rest-API anzubinden, um beispielsweise auf diesen Weg regelmäßig neue URNs zu registrieren oder zu aktualisieren, bietet die Deutsche Nationalbibliothek einen Java-Client an, um die bestehende URN-REST-API anzusprechen. Der Client dient zur Reduzierung des eigenen Programmieraufwandes und stellt eine modernere Alternative zu den bisherigen Möglichkeiten dar .
Technische Voraussetzungen:
- Die Verwendung von Java 8 oder kompatiblere JVM Sprache in der entsprechenden Version.
- Berechtigung zur Einspielung von URNS der eigenen Institutionen innerhalb des eigenen Namensraumes in Form von LOGIN / USER Credentials.
Umfangreiche Beispielmethoden, um über den REST-Client mit dem URN-System zu interagieren finden sie hier: Nutzungsbeispiele Java-Client .
Für die Nutzung des Java-Clients und möglich Folge daraus übernimmt die Deutsche Nationalbibliothek keine Verantwortung. Die eigenen Implementierung sind daher vor der produktiven Nutzung ausreichend zu testen. Hierzu kann die Sandbox Umgebung der URN-Service unter http://api.nbn-resolving.org/sandbox/v2/ genutzt werden.
Fehler oder Verbesserungshinweise können an die Service Adresse (urn-support@dnb.de) des URN-Service gemeldet werden. Zeitpunkt und Umfang der Anpassungen/ Fehlerbehebungen können jedoch nicht garantiert werden. URN-Release finde in der Regel dreimal pro Jahr statt, in denen bei freien Kapazitäten auch der Java-Client bearbeitet wird. Neu Versionen des Client werden an dieser Stelle angekündigt.
(Stand: 18. Dezember 2023)