Projektujemy dość złożone API REST, w którym większość I / O to obiekty zakodowane w JSON o określonej strukturze. Jednym z wyzwań, jakie znaleźliśmy, jest udokumentowanie API w taki sposób, aby ułatwić klientom publikowanie poprawnych danych wejściowych i wyjściowych procesu. Ponieważ dane zarówno danych wejściowych, jak i wyjściowych wymagają dość złożonych obiektów JSON, programiści klientów często wprowadzają błędy związane ze strukturą obiektów we / wy.

Mając do dyspozycji wszystkie webowe API JSON, liczyłbym na ogólne rozwiązanie, ale trudno mi znaleźć takie rozwiązanie. Zajrzałem do środkajson-schemat który jest schematem sprawdzania poprawności jsona, ale zarówno szkic IETF, jak i implementacje wydają się być dość niedojrzałe (mimo że istnieją już od jakiegoś czasu, co nie jest dobrym znakiem).

Nieco inne podejście oferujeBufory protokołu iApache Avro, gdzie schemat nie jest używany do walidacji, ale w rzeczywistości jest wymagany do kodowania / dekodowania komunikatu. Z tych 2 Avro wydaje się mieć raczej ograniczoną dokumentację i implementacje. ProtoBuf wydaje się lepszy, ale nie jestem pewien, czy naprawdę nadaje się do użycia w przeglądarce do wywoływania api JSON?

Teraz zaczynam wątpić, czy patrzę na to pod właściwym kątem. Czy są dostępne inne metody, aby mój interfejs API był nieco mocniejszy? Czy jest to formalny opis interfejsu API JSON REST / RPC, który pokonuje cel używania JSON?

Edytuj: 6 miesięcy po tym temacie, który znaleźliśmymangusta, która jest bardzo bliska temu, czego szukaliśmy.