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

Як API Resource формує обгортку відповіді: ключ data, with, additional і власні колекції ресурсів?

Ключ data. Ресурс, повернений з контролера, загортається в об'єкт з ключем data:

{ "data": { "id": 1, "name": "Olena" } }

Обгортка дає місце для метаданих поруч з даними і захищає від вразливості старих браузерів з JSON-масивом на верхньому рівні.

public static $wrap = 'user';            // власний ключ для цього ресурсу
JsonResource::withoutWrapping();          // вимкнути глобально (AppServiceProvider)

withoutWrapping() не діє на пагіновані відповіді: їм data потрібен, бо поруч ідуть links і meta.

Метадані верхнього рівня:

// у класі ресурсу - щоразу, коли ресурс є кореневим
public function with(Request $request): array
{
    return ['meta' => ['api_version' => '2026-10']];
}

// разово, з контролера
return UserResource::make($user)->additional(['meta' => ['cached' => false]]);

with() додається лише для кореневого ресурсу, не для вкладених.

Колекції:

return UserResource::collection(User::paginate(20));

Пагінована колекція автоматично отримує links (first, last, prev, next) і meta (current_page, total...). Для простої колекції - лише data.

Власний клас колекції - коли самій колекції потрібна логіка:

final class UserCollection extends ResourceCollection
{
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'summary' => ['active' => $this->collection->where('active', true)->count()],
        ];
    }
}

Керування HTTP-відповіддю:

return UserResource::make($user)
    ->response()
    ->setStatusCode(201)
    ->header('Location', route('users.show', $user));

Або в ресурсі - withResponse(Request $request, JsonResponse $response) для заголовків, що потрібні щоразу.

Типові помилки:

  • подвійна обгортка: toArray() повертає ['data' => [...]] - отримаєте data.data;
  • ключі колекції: за замовчуванням вони перенумеровуються; щоб зберегти, - public $preserveKeys = true;
  • формат для клієнтів - це контракт: вимкнення обгортки чи зміна $wrap на робочому API ламає всіх клієнтів, тож такі рішення приймають до першого релізу.

Докладніше в документації: API-ресурси: обгортання даних

43

Перевір себе

20 випадкових питань за спробу, після завершення - розбір кожної помилки

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