Un recurso dice qué se muestra de un modelo; una colección es una lista de recursos; una relación enlaza un recurso con otros. Esta página resume cómo escribir cada cosa y qué hace el paquete con ellas.
Si todavía no escribiste tu primer recurso, empieza por Primeros pasos.
Qué escribes para cada cosa
| Quieres | Escribes |
|---|---|
| Un recurso | ArticleResource::make($article) |
| Una colección | ArticleResource::collection($articles) (un arreglo, una colección o un paginador de longitud conocida) |
| Una colección paginada | ArticleResource::collection(Article::query()->jsonApiPaginate()) |
links o meta propios | jsonApiLinks($request) y jsonApiMeta($request) en el recurso, o ->additional([...]) |
| Una relación a uno o a muchos | Relationship::one($modelo, Clase::class) / Relationship::many($modelos, Clase::class) |
| Una relación sin cargarla | Relationship::unloaded()->links(...$this->relationshipLinks($request, 'author')) |
| El recurso relacionado vacío | AuthorResource::make(null), que responde data: null |
Colecciones y paginación
- Una colección vacía es
data: []. - La paginación suma
links(first,last,prev,next) ymeta.page(currentPage,perPage,lastPage,total). Esos enlaces conservansort,filter,includeyfieldstal como los mandó el cliente. Los nombres demeta.pagesiguen el estilo de los nombres: conkebabsalencurrent-page,per-page,last-pageytotal. - Un paginador simple o de cursor no se acepta, porque no sabe cuántas páginas hay, y lanza un error claro.
El tamaño de página, su tope y qué pasa si el cliente lo pasa están en Configuración.
Relaciones
Todavía en validación. Las relaciones, included y los endpoints de relación están probados con una API de referencia completa dentro de las pruebas del paquete, que validan cada respuesta contra el esquema oficial de JSON:API. Aún no se han validado en una aplicación real. Si algo no te encaja, abre un issue.
Dentro del recurso, Relationship::one() y Relationship::many() arman una relación con su resource linkage (el type y el id del relacionado). Una relación que no está cargada no sale, así que el paquete nunca dispara una consulta para completar un documento.
relationshipLinks($request, 'author') arma {self}/relationships/author y {self}/author a partir del links.self del propio recurso. Es opcional. Las rutas que esos enlaces señalan las escribes tú; mira Endpoints de relación.
Los recursos incluidos (included)
En included sale solo lo que el cliente pidió con include, y solo de relaciones ya cargadas y que el recurso muestra:
- Cada recurso aparece una sola vez, identificado por su
typey suid, y nunca repite a los que ya están endata. - Lo que un
fields[tipo]oculta tampoco se incluye, así el documento cumple el full linkage de la especificación.
El paquete no carga las relaciones por ti al armar el documento. Para cargarlas sin consultas de más (el problema N+1), usa jsonApiInclude([...]) en tu controlador, como en Primeros pasos. Un include sobre una relación que no se cargó se ignora en silencio.
Campos dispersos (fields)
fields[articles]=title recorta los atributos y las relaciones de ese tipo. Se quedan siempre el type, el id, los links y el meta. Los parámetros de consulta, con sus listas blancas, se explican en Parámetros de consulta.