Übersicht
Dieses Dokument beschreibt die offizielle REST-API des URN-Service in der Version v2.
Basis-Adresse und Versionierung
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:
Basis-Adresse der produktiven API
Die derzeit aktuelle Version ist v2. Im Normalfall wird nur eine Version der API angeboten. Nur beim Erscheinen einer neuen Version werden temporär zwei Versionen angeboten.
Sandbox
Der URN-Service bietet neben der produktiven API auch eine Sandbox-API an. Diese kann für Entwicklung und Tests von Anwendungen genutzt werden, um URNs und URLs zu Testzwecken registrieren und verwalten zu können, ohne den produktiven URN-Datenbestand zu beeinflussen.
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:
Basis-Adresse der Sandbox-API
Benutzer und Namensräume, die im Produktivsystem angelegt wurden, sind nicht automatisch in der Sandbox verfügbar. Bitte kontaktieren Sie den URN-Support, um die für Ihre Tests benötigten Benutzer und Namensräume einrichten zu lassen.
Datenformat
Alle Daten werden im JSON-Format mit UTF-8-Kodierung übertragen. Als Media-Typ wird application/json
erwartet und zurückgeliefert. Bei PATCH
-Anfragen kann alternativ auch der spezifischere Media-Typ application/merge-patch+json
angegeben werden.
In den Antworten des URN-Service werden leere Felder nicht weggelassen, sondern als null
ausgeliefert. Bei POST
-Anfragen, die an den URN-Service geschickt werden, können optionale Felder sowohl auf null
gesetzt werden oder weggelassen werden. Die JSON-Dokumente, die als PATCH
-Anfragen an den URN-Service geschickt werden, werden als JSON Merge-Patch (RFC 7386) interpretiert. D.h. bei übermittelten Feldern wird der Feldinhalt übernommen, nicht übermittelte Felder werden nicht geändert und auf null
gesetzte Felde werden gelöscht bzw. zurückgesetzt.
Zeitangaben erfolgen im ISO 8601 Format: YYYY-MM-DDTHH:MM:SS±hhmm
.
Authentifizierung
Anfragen auf Ressourcen, die Änderungen im URN-Service durchführen, bedürfen einer Authentizierung. Darüberhinaus unterscheiden sich einige Antworten des URN-Service in ihrem Umfang abhängig davon, ob sie mit oder ohne Authentizifierung durchgeführt werden. Beim Versuch, ohne Authentizierung auf eine Ressource zuzugreifen, die nur nach Authentifizierung zugänglich ist, wird entweder ein HTTP-Status 403 Forbidden
oder 404 Not Found
zurückgeliefert, abhängig davon, ob die Existenz der Ressource bekannt sein darf oder nicht. Beim Zugriff auf Ressourcen, die nicht zwingend eine Authentizierung benötigen, werden fehlerhaften Zugangsdaten ignoriert.
Als Authentizierungsverfahren wird HTTP Basic Authentication verwendet.
Die API unterstützt außerdem für fast alle Anfragen den Query-Parameter runas
. Mit diesem können Adminstratoren diese Methoden im Namen anderer Benutzer ausführen.
Parameter
Viele API-Methoden akzeptieren Parameter. Bei GET
-Anfragen werden diese als Query-Parameter übermittelt. Bei POST
- und PATCH
-Anfragen werden die Änderungen im Body der Anfrage mit dem Content-Type
application/json
oder – optional – bei PATCH
-Anfragen mit dem Content-Type
application/merge-patch+json
übermittelt.
Der Parameter runas
wird unabhängig von der Anfrage immer als Query-Parameter übermittelt.
HTTP-Verben
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
Hypermedia
Die URN-Service API verwendet URLs für Referenzen zwischen Ressourcen. Sie dienen dazu, explizite URLs anzbieten, die API-Clients verwenden können, sodass sie keine eigenen URLs konstruieren müssen.
Mit einem GET
-Request auf die Basis-Adresse können Sie eine Liste aller Endpunkte in der API abrufen.
Paging
TODO: Die aktuell generierten Link-Header sind nicht korrekt. Evtl. wäre es besser stattdessen die page, und per-page-Logik von Github zu nutzen.
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 auf die erste, letzte, vorhergehende und folgende Ergebnisseite verweisen:
Link: <http://api.nbn-resolving.org/v2/urns?offset=0&count=20>; rel="first",<http://api.nbn-resolving.org/v2/urns?offset=0&count=20>; rel="previous",<http://api.nbn-resolving.org/v2/urns?offset=40&count=20>; rel="next",<http://api.nbn-resolving.org/v2/urns?offset=0&count=20>; rel="last"
Referenz
Eine detaillierte Übersicht über alle Befehle der REST-API wird als Teil der REST-API unter docs/index.html
angeboten.