¿Qué es JSON:API?

JSON:API es una especificación para construir APIs basadas en JSON con una forma de respuesta consistente. Define convenciones para recursos, relaciones, links, errores, sparse fieldsets, ordenación, filtrado y paginación.

El objetivo no es reemplazar JSON. JSON es el formato de datos; JSON:API es un conjunto de reglas sobre cómo una API debe organizar ese JSON.

Cómo se ve JSON:API

Una respuesta JSON:API simple suele envolver recursos en un objeto o array data:

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API basics"
    }
  }
}

type e id identifican el recurso. attributes contiene campos normales. relationships puede describir links a otros recursos sin forzar que cada respuesta duplique objetos anidados.

Por qué los equipos usan JSON:API

JSON:API es útil cuando varios clientes necesitan payloads predecibles:

• Las apps frontend pueden parsear respuestas con supuestos compartidos.
• Los errores de API pueden seguir una estructura única.
• Paginación, relaciones y links pueden mantenerse consistentes entre endpoints.
• La documentación puede centrarse en campos de recursos en lugar de reinventar la forma de respuesta cada vez.

Puede reducir convenciones de API personalizadas, especialmente en productos grandes.

Cuándo JSON:API puede ser demasiado

JSON:API también es más estructurado de lo que muchas APIs pequeñas necesitan. Para un servicio interno diminuto, una respuesta JSON simple puede ser más fácil de leer y mantener.

Considera JSON:API cuando tu API tiene muchos tipos de recursos, relaciones, clientes y contratos de larga duración. Omítelo cuando el sobre extra y las convenciones añadan más confusión que consistencia.

Consejo práctico de depuración

Cuando inspecciones una respuesta JSON:API, comprueba primero data, attributes, relationships, included y errors. Pega una muestra en Formateador JSON para expandir la estructura antes de compararla con docs o schemas.