# Formate

## Zeichensatz / Kodierung

Unabhängig vom Format erfolgt die Übergabe und Rückgabe der Daten immer `<span class="n">UTF8</span>` 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](https://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:

<div id="bkmrk-format-code-verwende"><div><table><thead><tr><th>Format</th><th>Code</th><th>Verwendet</th><th>URL-Parameter</th></tr></thead><tbody><tr><td>JSON</td><td>`<span class="n">json</span>`</td><td>**Standard**</td><td>`<span class="o">?</span><span class="n">format</span><span class="o">=</span><span class="n">json</span>` (nicht notwendig,da Standard)</td></tr><tr><td>XML</td><td>`<span class="n">xml</span>`</td><td>explizite Angabe</td><td>`<span class="o">?</span><span class="n">format</span><span class="o">=</span><span class="n">xml</span>`</td></tr></tbody></table>

</div></div>JSON Endpunkt aufrufen

<div id="bkmrk-"></div><table class="codehilitetable" id="bkmrk-post-%2Fendpunkt-url-%23"><tbody><tr><td class="code"><div>```
POST /endpunkt-url
<span class="c1"># oder explizit</span>
POST /endpunkt-url?format<span class="o">=</span>json
```

</div></td></tr></tbody></table>

XML Endpunkt aufrufen

<div id="bkmrk--0"></div><table class="codehilitetable" id="bkmrk-post-%2Fendpunk-url%3Ffo"><tbody><tr><td class="code"><div>```
POST /endpunk-url?format=xml
```

</div></td></tr></tbody></table>

Achtung

Der `<span class="n">format</span>` Parameter muss sowohl bei lesenden (`<span class="k">GET</span>`), als bei schreibenden (`<span class="n">POST</span>`,`<span class="n">PUT</span>`) 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.

<div id="bkmrk--2"></div><table class="codehilitetable" id="bkmrk-%7B%22a%22%3A%22b%22%2C%22c%22%3A%22d%22%7D"><tbody><tr><td class="code"><div>```
    <span class="p">{</span><span class="nt">"a"</span><span class="p">:</span><span class="s2">"b"</span><span class="p">,</span><span class="nt">"c"</span><span class="p">:</span><span class="s2">"d"</span><span class="p">}</span>  
```

</div></td></tr></tbody></table>

ist äquivalent zu:

<div id="bkmrk--3"></div><table class="codehilitetable" id="bkmrk-%7B-%22a%22%3A-%22b%22%2C-%22c%22%3A-%22d%22"><tbody><tr><td class="code"><div>```
    <span class="p">{</span>
        <span class="nt">"a"</span><span class="p">:</span> <span class="s2">"b"</span><span class="p">,</span>
        <span class="nt">"c"</span><span class="p">:</span> <span class="s2">"d"</span>
    <span class="p">}</span>  
```

</div></td></tr></tbody></table>

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](https://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 `<span class="n">format</span>` 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 `<span class="n">format</span>`mit dem Wert `<span class="n">xml</span>` zu verwenden.

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

`<span class="err">POST /api/token/?format=xml</span>`

### Besonderheiten XML-Format

#### Root-Element

XML-Dokumente werden **immer** mit dem Element `<span class="o"><</span><span class="n">root</span><span class="o">></span>` beginnen und entsprechend mit `<span class="o"></</span><span class="n">root</span><span class="o">></span>` enden

Beispiel:

<div id="bkmrk-xml-0"><label for="__tab_1_0">XML</label><div></div></div><div id="bkmrk--5"></div><div id="bkmrk-%3Croot%3E-%3C%21---es-folgt"><div><table class="codehilitetable"><tbody><tr><td class="code"><div>```
 <span class="nt"><root></span>
    <span class="c"><!-- Es folgt das eigentliche Dokument zur Übergabe --></span>
 <span class="nt"></root></span>
```

</div></td></tr></tbody></table>

</div></div>#### Listen / Arrays

Array Elemente werden **immer** mit dem Tag `<span class="o"><</span><span class="n">list</span><span class="o">-</span><span class="n">item</span><span class="o">></span>` versehen

Beispiel: Übergabe einer Liste von 3 Meldescheinen

<div id="bkmrk-xml-1"><label for="__tab_2_0">XML</label><div></div></div><div id="bkmrk--6"></div>```
 <root>
    <meldescheine>
        <list-item><!-- weitere Daten --></list-item>
        <list-item><!-- weitere Daten --></list-item>
        <list-item><!-- weitere Daten --></list-item>
    </meldescheine>
    <!-- weitere Daten -->
 </root>
```