Ü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.

...

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.

...

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.

...

Zeitangaben erfolgen im ISO 8601 Format in UTC: YYYY-MM-DDTHH:MM:SS.sssZ.

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.

...

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.

Fehler

Wenn eine Anfrage an die URN-Service API fehlschlägt, enthält die Antwort ein JSON-Objekt mit einer genaueren Fehlermeldung:

...

Aus technischen Gründen werden Fehler allerdings teilweise auch als HTML-Dokument ausgeliefert.

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.

...

In allen Elementen, die von der URN-Service API ausgegeben werden, ist ein self-Feld enthalten, das eine kanonische URL-Referenz auf das Element enthält. Beim Neuanlegen von Elementen ist außerdem in der Antwort der API der HTTP-Header Location enthalten, mit der kanonischen URL-Referenz des neuen Elements.

Paging

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.

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"

Referenz

Eine detaillierte Übersicht über alle Befehle der REST-API wird als Teil der REST-API unter docs/index.html angeboten.

...