Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Що таке специфікація 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

1

Схожі питання