Design de resposta JSON RESTful: como e uma boa API
2024-06-28
Quando cada endpoint inventa seu proprio formato, o cliente acumula adaptadores. Uma convencao pequena e consistente evita muito retrabalho.
Envelope
Voce pode usar { data, meta, errors }; o principal e manter consistencia entre endpoints.
{ "data": { "id": 1 }, "meta": { "requestId": "abc" } }Erros
Combine status HTTP com codigo de maquina, mensagem humana e detalhes por campo.
Paginacao
Escolha cursor ou offset para todo o produto e padronize nomes das listas.
Nomes e tempo
Nao misture camelCase e snake_case; use datas ISO 8601 de forma uniforme.
Evolucao
Em v1 priorize mudancas aditivas; para breaking changes, versione e atualize OpenAPI com fixtures.