Formate

Zeichensatz / Kodierung

Unabhängig vom Format erfolgt die Übergabe und Rückgabe der Daten immer UTF8 kodiert. Nutzt Ihre Anwendung eine andere Zeichen-Kodierung (z.B. ISO-8859-1), so müssen die Buchungs-Daten vor der Übergabe in das entsprechende Format konvertiert werden.

Validierung der Anfragen

Alle schreibenden Anfragen (z.b. das Buchen eines Meldescheins) mithilfe eines JSON-Schemas validiert, um gültigen Datenaufbau zu gewährleisten. Entsprechende Schemata sind unter den jeweiligen Punkten der Dokumentation vermerkt.

Offizielle Dokumentation und Syntax-Erklärung unter json-schema.org

Info

Anfragen in einem anderen Format (z.B.) werden ebenfalls über die Schemata geprüft, werden zurvor jedoch intern in JSON umgewandelt.

Unterstützte Formate

Die Schnittstelle kann mit verschiedenen Formaten verwendet werden. Diese werden in den folgenden Punkten erläutert und es werden Besonderheiten hervorgehoben.

Folgende Formate werden unterstützt:

JSON Endpunkt aufrufen

POST /endpunkt-url
# oder explizit
POST /endpunkt-url?format=json

XML Endpunkt aufrufen

POST /endpunk-url?format=xml

Achtung

Der format Parameter muss sowohl bei lesenden (GET), als bei schreibenden (POST,PUT) in als URL-Parameter übergeben werden, wenn ein anderes Format, als der Standard verwendet werden soll.

JSON

Es kann nur gültiger JSON Syntax nach der Spezifikation angenommen werden werden. Leerstellen und/oder Zeilenumbrüche sind hierbei nicht relevant.

    {"a":"b","c":"d"}  

ist äquivalent zu:

    {
        "a": "b",
        "c": "d"
    }  

Bibliotheken, die zur Erstellung des JSON Formats verwendet werden können, finden sich in allen gängigen Programmiersprachen sowie umgebungen, was die Implementierung vereinfacht. Eine Auflistung gängiger Bibliotheken sind unter json.org aufgelistet.

Offizielle Spezifikation und Beispiele: json.org

XML

Die API lässt sich ebenfalls über das XML-Format ansprechen. Alle URL-Endpunkte der API bleiben bestehen müssen jedoch mit dem format Parameter übergeben werden (siehe unten)

Info

Sowohl Übergabe, als auch Rückgabe der API werden in XML übermittelt.

URL Parameter

Um das XML Format zu verwenden ist es notwendig hinter allen aufrufenden URLs den GET Parameter formatmit dem Wert xml zu verwenden.

Um eine Authentizierung im XML-Format aufzurufen lautet die URL somit:

POST /api/token/?format=xml

Besonderheiten XML-Format

Root-Element

XML-Dokumente werden immer mit dem Element <root> beginnen und entsprechend mit </root> enden

Beispiel:

 <root>
    <!-- Es folgt das eigentliche Dokument zur Übergabe -->
 </root>

Listen / Arrays

Array Elemente werden immer mit dem Tag <list-item> versehen

Beispiel: Übergabe einer Liste von 3 Meldescheinen

 <root>
    <meldescheine>
        <list-item><!-- weitere Daten --></list-item>
        <list-item><!-- weitere Daten --></list-item>
        <list-item><!-- weitere Daten --></list-item>
    </meldescheine>
    <!-- weitere Daten -->
 </root>