Как сделать JSON ответ в API Laravel

Если у вас есть достаточно сложное приложение на Laravel, скорее всего в вашем проекте используется API.

Когда реализовываешь такое API то возникает проблема: как сделать JSON ответ для API?

Если вы уже хорошо знаете что такое API, то пропускайте предисловие и переходите сразу к решению в конце статьи.

Для чего нужен API в приложении?

Есть несколько применений для API:

Разделение Frontend и Backend вашего сайта, например при использовании Frontend фреймворков Vue, React, или даже без них. В этом случае API будет предоставлять вашему фронтенду все необходимые данные и обслуживать действия пользователя на сайте.
API для мобильного приложения: аналогично предыдущему, только фронтендом является мобильное приложение, а не страница сайта.
Third-party интеграция: если вы даёте другим разработчикам возможность интегрироваться с вашей системой.
Обработка колбеков: при интеграции с такими внешними системами как CRM или платёжными шлюзами, может потребоваться обновлять данные на сайте по входящему HTTP запросу.

И так далее.

Формат API

Самым распространённым вариантом для формата API в 2024 году является JSON и HTTP.

Это универсальные форматы, которые понятны большинству существующих систем, а потому и подключаемые чаще и проще остальных.

Как подключить API в Laravel

До версии Laravel 10 включительно в шаблон стандартного приложения уже было включено настроенное API.

Но начиная с версии Laravel 11 это изменили. Теперь “из коробки” в приложении нет API.

Подключить его можно командой:

php artisan install:api

Как настроить JSON ответ в API

Если не настроить JSON формат ответа API, то при ошибке со стороны клиента API в ответ вывалится невнятная “портянка” из HTML тегов.

Это не смертельно, но неприятно.

Причина в том, что Laravel не отдаёт при ошибке ответ JSON если не указан заголовок:

Accept: application/json

Гораздо логичнее отдавать ответ с API в формате JSON всегда, если не указано обратное.

Laravel этого делать не умеет, но можно это пофиксить самостоятельно.

Шаг 1. Создаём Middleware

app/Http/Middleware/ForceJsonResponseMiddleware.php

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

/**
 * App/Http/Kernel
 *
 * 'api' => [
 *            ForceJsonResponseMiddleware::class,
 *            ...
 *          ],
 */
class ForceJsonResponseMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        $request->headers->set('Accept', 'application/json');

        return $next($request);
    }
}

Шаг 2. Регистрируем Middleware в приложении

app/Http/Kernel.php

<?php

namespace App\Http;

...

class Kernel extends HttpKernel
{
    ...
    
    protected $middlewareGroups = [
        ...

        'api' => [
            ForceJsonResponseMiddleware::class,
            ...
        ],
    ];

	...
}

Теперь в каждый запрос к API будет добавлен заголовок “Accept: application/json”, и ответ будет всегда в формате JSON.