Ao construir uma API, você pode precisar de uma camada de transformação que fica entre seus modelos Eloquent e as respostas do seu aplicativo. Por exemplo, você pode desejar exibir determinados atributos para um subconjunto de usuários e não outros, ou pode desejar sempre incluir determinados relacionamentos na representação JSON de seus modelos. Com o uso de Recursos (API Resources), você pode personalizar a estrutura dos dados, adicionar metadados, transformar e filtrar informações antes de enviá-las como resposta em formato JSON.

Vamos ver um exemplo de como criar e usar um API Resource em Laravel:

1. Criando um API Resource: Para criar um API Resource, você pode usar o comando Artisan make:resource. Suponha que você tenha um modelo Post que deseja transformar em formato JSON:

   php artisan make:resource PostResource
   

   Isso criará um arquivo PostResource.php em app/Http/Resources com a estrutura básica para o recurso.

2. Definindo a Transformação: No arquivo PostResource.php, você pode personalizar a transformação dos dados do modelo. Por exemplo, você pode selecionar quais atributos do modelo devem ser incluídos na resposta, formatar valores, adicionar metadados e assim por diante.

   <?php
   
   namespace App\\\\Http\\\\Resources;
   
   use Illuminate\\\\Http\\\\Resources\\\\Json\\\\JsonResource;
   
   class PostResource extends JsonResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'title' => $this->title,
               'content' => $this->content,
               'created_at' => $this->created_at->format('Y-m-d H:i:s'),
               // Outros atributos do modelo, se necessário
           ];
       }
   }
   

3. Usando o API Resource na API: Agora que o recurso PostResource está criado, você pode usá-lo em seus controladores para transformar os dados do modelo antes de enviá-los como resposta da API.

   Por exemplo, no controlador PostController, você pode retornar uma coleção de recursos PostResource ao listar todos os posts:

   <?php
   
   namespace App\\\\Http\\\\Controllers;
   
   use App\\\\Http\\\\Resources\\\\PostResource;
   use App\\\\Models\\\\Post;
   use Illuminate\\\\Http\\\\Request;
   
   class PostController extends Controller
   {
       public function index()
       {
           $posts = Post::all();
           return PostResource::collection($posts);
       }
   }
   

   A chamada PostResource::collection($posts) transformará cada post no formato definido no toArray() do PostResource antes de enviar a resposta como JSON.

   Para retornar um único post em detalhes, você pode usar o mesmo recurso PostResource:

   public function show($id)
   {
       $post = Post::find($id);
       return new PostResource($post);
   }
   

Os API Resources também facilitam a manutenção, pois centralizam a lógica de transformação em um único local, tornando o código mais organizado e legível.

Laravel - The PHP Framework For Web Artisans