Endpoints de relación

Un endpoint de relación, como /articles/1/relationships/author, devuelve solo el linkage de una relación (el type y el id del relacionado) y permite cambiarlo. Las rutas y los controladores los escribes tú; el paquete valida la forma del documento y arma la respuesta.

Leer una relación

Una Relationship devuelta desde un controlador es la respuesta de un endpoint de relación: {jsonapi, links, data, meta} con solo el linkage.

public function author(string $article) {
  $model = Article::query()->with('author')->findOrFail($article);

  return Relationship::one($model->author, AuthorResource::class)->links(
    self: route('articles.relationships.author', [$model]),
    related: route('articles.author', [$model]),
  );
}

Escribir una relación

Para escribir una relación, lee el linkage con RelationshipDocument: el paquete ya validó su forma (mira Leer el documento de entrada). Lo que depende de tu modelo lo revisas tú, con estos códigos:

use MundoProgra\JsonApi\Exceptions\JsonApiException;
use MundoProgra\JsonApi\Http\Requests\RelationshipDocument;

public function updateAuthor(Request $request, string $article) {
  $document = RelationshipDocument::of($request);        // data() es null, un identificador o una lista; isList() dice cuál

  if ($document->isList()) {                             // una lista donde va un identificador
    throw JsonApiException::make(status: 422, detail: 'A to-one relationship takes one identifier or null.', pointer: '/data');
  }

  $identifier = $document->data();                       // ['type' => 'authors', 'id' => '3'] o null

  if ($identifier !== null && $identifier['type'] !== 'authors') {
    throw JsonApiException::make(status: 409, pointer: '/data/type');          // el tipo no es el de la relación
  }

  $author = $identifier === null ? null : Author::find($identifier['id'])
    ?? throw JsonApiException::make(status: 404, pointer: '/data');            // el recurso no existe

  // ... asociar, guardar y responder con la relación resultante (`200`)
}

Qué hace cada verbo

• PATCH reemplaza la relación.
• POST agrega elementos a una relación a muchos.
• DELETE quita elementos de una relación a muchos.

El ejemplo completo, con lecturas, escrituras y errores, está en tests/Fixtures/ReferenceApi. Los códigos de error están en Errores.