Що таке специфікація JSON:API і як її підтримує Laravel 13?

JSON:API - специфікація формату JSON-відповідей і правил запитів для API. Замість того, щоб кожна команда вигадувала власну структуру, вона фіксує готові рішення.

{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": { "title": "Laravel 13", "published_at": "2026-09-30T10:00:00Z" },
    "relationships": {
      "author": { "data": { "type": "users", "id": "7" } }
    }
  },
  "included": [
    { "type": "users", "id": "7", "attributes": { "name": "Оля" } }
  ]
}

Що стандартизує:

• структура ресурсу: type, id (завжди рядок), attributes, relationships, links, meta;
• include - пов'язані ресурси в масиві included, кожен один раз, навіть якщо на нього посилаються десятки записів;
• sparse fieldsets - fields[posts]=title;
• сортування, пагінація, фільтрація - назви параметрів (sort=-published_at, page[...], filter[...]);
• формат помилок - масив errors з status, code, title, detail, source.pointer;
• медіатип - application/vnd.api+json.

Laravel 13 має вбудовані JSON:API-ресурси:

php artisan make:resource PostResource --json-api

class PostResource extends JsonApiResource
{
    public $attributes = ['title', 'body', 'published_at'];

    public $relationships = ['author', 'comments'];
}

JsonApiResource формує структуру data/attributes/relationships, обробляє include і fields із запиту, серіалізує зв'язки лише коли клієнт їх запросив і виставляє правильний Content-Type. Глибину вкладених include обмежує JsonApiResource::maxRelationshipDepth(). Розбір фільтрів і сортування Laravel лишає за пакетами на кшталт spatie/laravel-query-builder.

Переваги стандарту:

• не потрібно вигадувати й документувати формат - достатньо послатися на специфікацію;
• готові клієнтські бібліотеки вміють нормалізувати included, будувати запити з include і fields;
• дедуплікація пов'язаних ресурсів зменшує розмір відповідей.

Недоліки:

• багатослівність: для простих API структура надлишкова, а клієнту без бібліотеки доводиться «склеювати» relationships з included;
• рядкові id і обгортки незвичні для фронтенд-розробників;
• проблеми продуктивності з include на сервері лишаються: кожен дозволений зв'язок треба завантажувати жадібно.

Коли обирати: публічні API й інтеграції, де передбачуваність формату важить більше за компактність, або коли клієнти вже використовують JSON:API-бібліотеки.

Докладніше в документації: Специфікація JSON:API