Übersicht

Dieses Dokument beschreibt die offizielle REST-API des URN-Service in der Version v2.

Das URN-Datenmodell

Berechtigungen

...

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:

Die derzeit aktuelle Version ist v2. Im Normalfall soll wird nur eine Version der API dauerhaft angeboten werden. Nur beim Erscheinen einer neuen Version sollen werden temporär zwei Versionen angeboten werden.

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 einfach ignoriert.

Als Authentizierungsverfahren wird HTTP Basic Authentication verwendet.

Datenformat

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:

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 Alle Daten – bis auf die URN-Vorschläge – werden im JSON-Format mit UTF-8-Kodierung übertragen. Als Media-Typ wird wird application/json erwartet und zurückgeliefert. Eine Ausnahme stellen die Bei PATCH-Anfragen dar. Hier wird bis auf eine Ausnahme (das Ersetzen aller eigenen URLs), das JSON-Derivat Merge-Patch mit dem Media-Typ kann alternativ auch der spezifischere Media-Typ application/merge-patch+json verwendet angegeben werden.

in In den Antworten des URN-Service werden leere Felder nicht weggelassen, sondern als null ausgeliefert. Bei Bei POST-Anfragen, die an den URN-Service geschickt werden, können optionale Felder sowohl auf null gesetzt werden oder weggelassen werden. Bei Die JSON-Dokumente, die als PATCH-Anfragen kommt in RFC 7386 beschriebene Logik zur Anwendungan den URN-Service geschickt werden, werden als JSON Merge-Patch (RFC 7386) interpretiert. D.h. nicht übermitteltes Feld wird nicht geändert, ein auf null gesetztes Feld wird 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:SSZ  PRÜFENSS±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.

Referenz

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

Sandbox

Der URN-Service bietet neben der produktiven API noch 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.

...

Los gehts: Beispiele

Mit einem GET-Request auf die Basis-Adresse können Sie eine Liste aller Endpunkte in der API abrufen:

curl https://api.nbn-resolving.org/

...

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.

...

v2/