Hier werden nun allgemeine Regeln zur Api beschrieben.
Das Datenformat der Api sind JSON. Die Anfrage ist in JSON und auch die Antwort ist in JSON. Es gibt ein paar kleine Ausnahmen, wo die Antwort ein Binary Stream ist, wenn man zum Beispiel ein Excel Report haben will, oder Rohdaten haben möchte.
In den Spezifikationen tauchen Datentypen auf. Dabei ist zu Beachten, der Type Integer ist eine maximal 32bit bit breite Zahl. Das bedeutet im Sinne von JSON, ist es eine Zahl. Beispiel:
{ "einInteger": 4711 }
Im Gegensatz dazu ist ein Long eine Zahl, die mehr als 53bit hat, also meist 64bit, und somit im Sinne von JSON als ein String übertragen werden muss. Beispiel:
{ "einLong": "4711" }
Dabei ist es natürlich unerheblich, ob ein Long nur die Zahl 1 beinhaltet, die wird natürlich als “1” übertragen, da der Datentyp des Feldes entscheidend ist.
Ein Api Aufruf kann grundsätzlich immer nur ein Befehl beinhalten. Wenn man also später zum Beispiel eine Änderung an zwei Geräten machen will, muss man auch zwei Aufrufe machen. Die Idee mit mehreren Befehlen arbeiten zu wollen, wurde verworfen, da es dann nicht mehr eindeutig wäre, wenn etwas nicht geklappt hat. Das würde den Client Code viel zu stark verkomplizieren.
Auf ein REST Interface wurde verzichtet. REST scheint zwar nett zu sein, ist mir aber viel zu limitiert und viel zu aufwendig und hässlich, wenn es um Filterungen geht. Diese Url-Based Filterung ist extrem unflexibel und sieht auch nicht schön aus. Mal ganz davon zu schweigen das es ständig ein Encoding und Decoding bedarf. Aus diesem Grunde hat die Yuna Api mit einer REST Schnittstelle nicht viel gemeinsam.
Grundsätzlich ist immer ein sogenannter AuthKey zu erstellen, der aktiviert oder deaktiviert werden kann. Ohne den authKey bekommt man entsprechende Meldungen, dass dieser fehlt.
Aktuell fehlt es noch, aber zu jedem Key können Berechtigungen definiert werden. Das fehlt aktuell. Für Listen der aktuellen Datenbestände ist es aktuell nicht vorgesehen dort Berechtigungen zu vergeben. Erst wenn Änderungen am Datenbestand getätigt werden, erst dann wird das wichtig.
Mehr dazu findet man auch unter Authorization
Grundsätzlich gilt, dass sämtliche Daten einer Anfrage immer auch in der Antwort mitgegeben werden. Ausnahme sind dabei Datenfelder die nicht in der Datenstruktur enthalten sind. Es gibt weiterhin spezielle Client Parameter, die ein Client setzen kann, die dann in der Antwort wieder auftauchen. Damit kann der Client Asynchron arbeiten, da zum Beispiel eine Transaktion-Nummer vom Client in der Antwort wieder auftaucht.
Fehlermeldungen werden grundsätzlich im Content der Antwort gemeldet. Auf eine Statusmeldung innerhalb der Transportschicht wurde verzichtet. Das bedeutet bei einer HTTP Verbindung wird der HTTP Status grundsätzlich HTTP 200 OK sein. Ob der Api Aufruf korrekt war, steht innerhalb des JSON Content.
Die einzigen Transportschicht-Fehler werden nur bei ungültigen JSON oder ungültigen Methoden (GET, HEAD, OPTION usw.) gemeldet.
Unter Fehlermeldungen wird gezeigt wie so eine Fehlermeldung aussehen könnte.
Man findet auf den Hilfeseiten sehr viele Beispiele, jedoch sind die JSON nicht immer vollständig. Insbesondere bei den Actions fehlt zum Beispiel immer der Auth Key und in der Antwort auch das Timing. Wenn man noch nie die Hilfe gelesen hat, und gleich sofort mit dem Beispiel einer Action anfängt, wird man kein Spass haben. Auf der einen Seite wäre es toll überall vollständig Beispiele zu haben, was aber dann ein Problem wird, wenn man was an den Grundlagen ändert, dann passiert es nämlich das man alle Beispiele anfassen müsste, und das einem dort etwas durch die Lappen geht ist sehr wahrscheinlich, und dann bekommt man nach und nach eine Dokumentation ohne Wert. Daher werden in den Beispielen die Grundlagen vorausgesetzt und dann auch weggelassen, damit Grundlagen Änderungen kein Domino-Effekt auslösen und alles unbrauchbar machen.
Corvus Help - 28.February 2026 03:33:38 UTC - Commit 667ccc2e