Inicio · MundoProgra JSON:API

Convierte una API de Laravel en un servicio JSON:API 1.1 de punta a punta: acepta y valida las peticiones en el estándar y responde en el estándar, tanto en éxito como en error.

Estado: versión 0.1.0, en validación. La API descrita aquí está completa, cubierta por pruebas en Laravel 10 a 13 y probada en una aplicación real. En 0.x la API puede cambiar entre versiones menores (con ^0.1 Composer solo instala 0.1.x).

Instalación → Un comando y listo: el paquete se descubre solo. Primeros pasos → Un recurso, un controlador y sus rutas, de principio a fin. Errores → Todos los códigos y el orden en que se comprueban. Configuración → Cada opción, su variable de entorno y su valor por defecto.

Qué es JSON:API

JSON:API es una especificación, no una librería: un acuerdo sobre cómo un servidor y un cliente intercambian datos en JSON por HTTP. Define la forma de las respuestas, de las peticiones que crean o cambian datos, de las relaciones entre recursos, de los parámetros de consulta y de los errores. El texto completo está en jsonapi.org/format.

Como todas las APIs que la siguen hablan igual, un cliente o una librería escritos para una sirven para otra, y el equipo ya no tiene que discutir cómo nombrar los campos, cómo paginar o cómo devolver un error.

Sus ideas principales:

Recursos: cada cosa que la API expone es un objeto con type e id, y sus datos van dentro de attributes.
Relaciones: un recurso apunta a otros por su type y su id, dentro de relationships. Con include se pueden traer en la misma respuesta, en included y sin repetirse.
Consultas con nombres fijos: include para traer relaciones, fields[tipo] para pedir solo algunos campos y sort para ordenar; page y filter están reservados para paginar y filtrar.
Errores uniformes: siempre un arreglo errors con el estado, un código y un source que señala qué campo o parámetro falló.
Un tipo de contenido propio: application/vnd.api+json, tanto en Accept como en Content-Type.

Así se ve una respuesta con un artículo y su autor:

{
  "jsonapi": { "version": "1.1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "Hola, JSON:API" },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    },
    "links": { "self": "/articles/1" }
  },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "Ada" } }
  ]
}

Qué hace este paquete

Responde en JSON:API: recursos, colecciones paginadas, relaciones, included, links y meta, y todos los errores (incluidos los de validación, 401, 404, 405 y 500) como documentos de errores con source.pointer o source.parameter.
Valida lo que llega: las cabeceras (Accept y Content-Type), los parámetros de consulta (include, fields, sort, filter, page) y el documento del cuerpo, con el puntero exacto del miembro que falla.
Aplica la consulta a Eloquent con listas blancas que escribes tú: filtros, orden, paginación y carga anticipada de relaciones.
No registra rutas ni controladores: tú decides las URL y la lógica; el paquete se ocupa del formato.
Se activa solo al instalarlo, sin tocar bootstrap/app.php, Kernel ni Handler.

Requisitos

PHP 8.1 o superior
Laravel 10, 11, 12 o 13