Wir entwerfen eine ziemlich komplexe REST-API, in der die meisten E / A-Vorgänge JSON-codierte Objekte mit einer bestimmten Struktur sind. Wir haben festgestellt, dass es eine Herausforderung ist, die API so zu dokumentieren, dass es für Kunden einfacher ist, korrekte Eingaben und Prozessausgaben zu erstellen. Da die Daten sowohl der Eingabe als auch der Ausgabe ziemlich komplexe JSON-Objekte erfordern, führen Client-Entwickler häufig Fehler ein, die sich auf die Struktur der E / A-Objekte beziehen.

Bei all den heutigen JSON-Web-APIs hätte ich auf eine allgemeine Lösung gehofft, aber es fällt mir schwer, eine zu finden. Ich habe nachgesehenjson-Schema Dies ist ein JSON-Validierungsschema, aber sowohl der IETF-Entwurf als auch die Implementierungen scheinen ziemlich unausgereift zu sein (obwohl sie schon eine Weile existieren, was kein gutes Zeichen ist).

Einen etwas anderen Ansatz bietetProtokollpuffer undApache Avro, wobei das Schema nicht zur Validierung verwendet wird, sondern für die Kodierung / Dekodierung der Nachricht tatsächlich benötigt wird. Von diesen beiden scheint Avro nur über eine begrenzte Dokumentation und Implementierung zu verfügen. ProtoBuf scheint besser zu sein, aber ich bin nicht sicher, ob dies wirklich geeignet ist, um im Browser eine JSON-API aufzurufen?

Jetzt beginne ich zu zweifeln, ob ich das aus dem richtigen Winkel betrachte. Gibt es andere Methoden, um meine API ein bisschen typischer zu machen? Oder ist eine formale Beschreibung einer JSON-REST / RPC-API etwas, das den Zweck der Verwendung von JSON zunichte macht?

Edit: 6 Monate nach diesem Thema haben wir gefundenMungo, was dem sehr nahe kommt, wonach wir gesucht haben.