Hallo @avonwyss und @FlowPro
Hier meine Antworten zu euren Fragen:
In der Doku hat es mehrere schreibende Operationen mit der GET-Methode (z.B. Periode ändern, Setting ändern, Order zu Dossier hinzufügen oder entfernen). Das entspricht nicht den Erwartungen (und der HTTP-Spezifikation, welche für GET verlangt dass es "safe" und "idempotent" ist). Ist das ein Fehler in der Doku, kann ich die Aufrufe mit einem POST implementieren?
Dies ist ein Fehler in der Doku, diese Operationen gehen alle mit POST. Wahrscheinlich weil sie sowohl mit GET als auch POST gehen, stellt die Doku GET dar. Werden wir beheben.
Der Filter bei der Suche ist ziemlich try-and-error, zum Beispiel funktioniert ein Filter auf das "date"-Property eines Order nicht wenn ich das Datum im gleichen Format übermittle wie es vom Server zurückgegeben wird. Der Server gibt das im JSON wie folgt zurück: "date": "2022-01-03 00:00:00.0" - im Filter eingesetzt kommt damit aber kein Resultat, ich muss date=2022-01-03 (ohne Zeit) übergeben damit es klappt. Ist das ein Bug oder gewollt?
Die JSONs wurden primär für das UI-Framework ExtJS formatiert, und dieses erwartet für ein Datum dieses lange Format mit Millisekunden. Die Daten in der Datenbank haben allerdings in den meisten Fällen keine Uhrzeit (sind vom Typ DATE und nicht DATETIME). Darum muss man zum filtern nur das Datum mitgeben, ohne Uhrzeit. Ist eine bedauerliche Inkonsistenz, aber zurzeit einfach so. Das könnten wir beheben, indem wir die Uhrzeit entfernen beim date-Filter. Ist notiert.
Wenn ich ein OrderBookEntry erstelle wird eine accountId verlangt auch wenn eine gültige templateId (welche ja die accountId impliziert) mitgebe, gleiches scheint entgegen der Dokumentation für die Description zu gelten (der lokalisierte Name des Templates sollte ja benutzt werden, das scheint aber nicht der Fall zu sein). Das ist mühsam, denn so muss man diese Daten erst in Erfahrung bringen (und den richtigen lokalisierten Text für die Sprache finden)...
Es gibt sicherlich noch einige solche Optimierungen für API-Nutzer. Denn auch hier spielt dies für das UI von CashCtrl keine Rolle, da diese Informationen im Dialog vorausgefüllt werden, also immer mitgeschickt werden.
Ist notiert.
Aus dem Journal-Import werde ich nicht schlau. Es gibt kein Delete, und wenn man Execute macht so wird die Import-Session auch nicht entfernt. Im UI scheint der Import durch das Schliessen des Tabs entfernt zu werden, wie ist das via API vorgesehen?
Im UI wird nur die sogenannte Tab-Session geschlossen (existiert in der API nicht). Die Import-Session (oder besser: der Import) bleibt immer bestehen in der Datenbank, wenn Buchungen importiert wurden (wird lediglich gelöscht, wenn man keine einzige Buchung daraus importiert hat). Die Imports und Import-Buchungen werden im UI nirgends dargestellt, aber bleiben zur Nachforschung in der Datenbank. Auch haben wir vor, in Zukunft einmal eine Liste der Imports darzustellen und löschbar zu machen.
Die verschiedenen Endpunkte, welche kein JSON zurückgeben (z.B. balance, exchangerate, setting, sequencenumber) , geben in den Headern "text/html" an, obschon der Inhalt ja nicht HTML ist. Ausserdem stellt sich bei sequencenumber auch noch die Frage, ob GET die richtige HTTP-Methode ist...
Das wäre ein Bug. text/html ist wohl einfach der Default, wenn kein Content-Type gesetzt ist, und es sich nicht von der Endung ableiten lässt. Ich nehme aber an, dass man bei der Nutzung der API hier den Content-Type sowieso ignoriert.
Ich bin noch über eine weitere Inkonsistenz gestossen die mir Mühe macht, und zwar beim Auslesen eines InventoryArticle mit READ sind die Konteninfos nicht enthalten (salesAccountId und purchaseAccountId, welche auf der Kategorie definiert werden). Zusammen mit der Problematik, dass CashCtrl auch beim Setzen einer InventoryId bei einem OrderItem alle Felder mit den Infos des InventoryArticle ausgefüllt haben will, fehlt dann die Kontoinformation wenn man letzteren direkt mit READ bezogen hat.
Ist ebenfalls notiert. Hierzu könnte man als Workaround den InventoryCategory auch auslesen über die categoryId des InventoryArticle.
Einen wichtigen Punkt den ich zu deinen professionellen Punkten noch hinzufügen möchte:
Änderungen an einer API sollten zwingend an eine konsequente Versionierung gebunden sein. Sprich es darf nicht vorkommen das die CashCtrl Entwickler eine API-Änderung auf der aktuellen «/v1/» mal schnell produktiv schalten und somit den produktiven Betrieb einer Vielzahl von Apps allfällig riskieren.
Alle API-Änderungen, die die bestehende API gebrochen haben, sind Bugs, also nicht gewollt. Diese haben wir auch jeweils behoben. Denn grundsätzlich für die Version 1 der API machen wir nur rückwärtskompatible Änderungen, die die API nicht brechen. Eine Version 2 gäbe es nur bei einem totalen API-Overhaul. Für die Version 1 kann es aber vorkommen, dass wir teilweise Parameter umbenennen (selten), oder wie im Fall des vCard-Imports eine komplett neue API erstellen. In diesen Fällen gehen aber auch die alten Parameter und die alte vCard-Import-API, nur sind diese nicht mehr dokumentiert, sondern nur der neue Approach bleibt dokumentiert. So sparen wir uns Aufwand.
@avonwyss Mir fällt auf, dass die meisten Fragen eigentlich eher Bugreports sind 😉 Könntest du diese bitte fortan per Support-Anfrage berichten anstatt im Forum? Das Forum ist eigentlich eher für den Austausch in der Community gedacht, weniger als Bug-Tracker. Besten Dank!
