Diseno de respuestas JSON RESTful: como se ve una buena API
2024-06-28
Cuando cada endpoint usa una forma distinta, el cliente termina lleno de adaptadores. Un convenio pequeno pero consistente evita meses de friccion.
Envelope
Puedes usar { data, meta, errors }; lo importante es mantener consistencia en toda la API.
{ "data": { "id": 1 }, "meta": { "requestId": "abc" } }Errores
Combina estado HTTP con codigo de maquina, mensaje humano y detalles por campo.
Paginacion
Elige cursor u offset para todo el producto y usa nombres de listas consistentes.
Nombres y tiempo
No mezcles camelCase y snake_case; usa fechas ISO 8601 de forma uniforme.
Evolucion
En v1 privilegia cambios aditivos; para breaking changes, versiona y actualiza OpenAPI con fixtures.