Estamos projetando uma API REST bastante complexa, na qual a maioria das E / S são objetos codificados em JSON com uma estrutura específica. Um desafio que encontramos é documentar a API de uma maneira que facilite para os clientes postarem a entrada correta e processar a saída. Como os dados da entrada e da saída exigem objetos JSON bastante complexos, os desenvolvedores clientes geralmente introduzem erros relacionados à estrutura dos objetos de E / S.

Com toda a API da web JSON atualmente, eu esperava uma solução geral, mas estou tendo dificuldades para encontrar uma. Eu olhei parajson-schema que é um esquema de validação do json, mas tanto o rascunho da IETF quanto as implementações parecem ser bastante imaturas (mesmo que já existam há algum tempo, o que não é um bom sinal).

Uma abordagem ligeiramente diferente é oferecida porBuffers de protocolo eApache Avro, onde o esquema não é usado para validação, mas na verdade é necessário para a codificação / decodificação da mensagem. Destes 2, o Avro parece ter documentação e implementações bastante limitadas. ProtoBuf parece melhor, mas não tenho certeza se isso é realmente adequado para usar no navegador para chamar uma API JSON?

Agora estou começando a duvidar se estou olhando para isso do ângulo certo. Existem outros métodos disponíveis para tornar minha API um pouco mais forte? Ou uma descrição formal de uma API JSON REST / RPC é algo que anula o propósito de usar o JSON?

Edit: 6 meses após este tópico que encontramosmangusto, que é muito parecido com o que estávamos procurando.