3 Adressierung und Navigation
Die Basis für alle Endpunkte ist https://beispiel.org/api/, Hier in der Doku wird immer vollständige Anfrage-Pfad genannt. URLs sind case-insensitiv und enthalten keine Leerzeichen.
cmxOrganize ist ein objektorientiertes System, daher erfolgt auch der Zugriff in der API auch nach Klassen und Objekten sowie Klassen- und Objektmethoden. Die Grundfunktionalität (Auflisten, Lesen, Erstellen, Ändern, Löschen) ist für alle Klassen gleich und der Zugriff darauf erfolgt immer auf die gleiche Art, daher werden in dieser Dokumentation nicht alle Endpunkte dafür genannt.
Navigation
Bei den meisten Endpunkten liefert die API proaktiv weitere Endpunkte zurück, die verwendet werden können. Somit kann man sich wie mit Links im Web von Endpunkt zu Endpunkt navigieren. Auch weitere Seiten in der Paginierung von Listen werden so angegeben. Ein Navigationsobjekt hat folgendes Format:
{ "http_method": "GET", "url": "https://beispiel.org/api/veranstaltungen", "get_parameter": [ { "name": "seitenindex", "optional": true, "typ": "number" }, { "name": "abfrage", "optional": true, "typ": "string", "beschreibung": "Name der zu verwendenden Abfrage" } ]} Das Array get_parameter wird nur angegeben, wenn es auch mögliche GET-Parameter gibt.
Veraltete Endpunkte
Es kann vorkommen, dass wir Endpunkte (Klassen) umbenennen müssen. Die alten Endpunkte werden in so einem Fall weiterhin verfügbar sein, in den HTTP-Headern wird dann auf den neuen Namen des Endpunktes hingewiesen:
Deprecation: true Link: </api/klassen>; rel=latest-version, <https://cmxkonzepte.de/api-doku>; rel=deprecation 4 Datenaustausch
- Das Austauschformat ist grundsätzlich JSON.
- Nicht-ASCII-Zeichen sowie Sonderzeichen wie Schrägstriche werden von der API über Unicode-Escape-Sequenzen (z. B.
u00e4) oder über Backslashes escaped. In der Doku werden für bessere Lesbarkeit die Sonderzeichen direkt dargestellt. - Wenn weitere Formate verfügbar sind, können diese über den
Accept-Header angefragt werden - Das Antwortformat wird immer im
Content-Type-Header mitgeteilt - Beim Anliefern von Daten (POST/PUT) muss das verwendete Format ebenfalls mit dem
Content-Type-Header angegeben werden - Zeitstempel werden im ISO 8601-Format übertragen. Datumsangaben sind im Format JJJJ-MM-TT, Uhrzeit-Angaben in HH:MM:SS, beides in Lokalzeit (in aller Regel Europe/Berlin).
Fehler
Wenn Fehler auftreten, wird dies über den HTTP-Statuscode (4xx und 5xx) angezeigt. Clients müssen nach einer Abfrage den Statuscode prüfen und dementsprechende Fehlerbehandlungen implementieren.
Wenn Fehler auftreten, ist die Antwort immer ein JSON mit dem folgenden Format:
{ "success": false, "message": "Beispielfehlermeldung"} Je nach Art des Fehlers können auch noch weitere Informationen enthalten sein.