Пакетний ендпойнт виконує багато однотипних операцій одним запитом: імпорт тисячі товарів, позначення 200 повідомлень прочитаними, оновлення цін.
Навіщо, якщо є HTTP/2: мультиплексування знімає витрати на з'єднання, але кожен окремий запит - це окремі автентифікація, валідація, транзакція, запис у журнал, ліміт частоти. Для тисяч операцій пакет у рази ефективніший і для клієнта, і для сервера.
Проєктування:
POST /api/products:batchCreate
{"items": [{"sku": "A-1", "name": "..."}, {"sku": "A-2", "name": "..."}]}
Головне рішення - атомарність:
1. Усе або нічого - одна транзакція; при будь-якій помилці нічого не застосовується:
HTTP/1.1 422 Unprocessable Content
{"errors": {"items.17.sku": ["Такий SKU вже існує"]}}
Просто для клієнта, але одна погана позиція блокує всі інші.
2. Часткове виконання - кожна позиція окремо, у відповіді результат для кожної:
HTTP/1.1 200 OK
{
"results": [
{"index": 0, "status": 201, "id": 501},
{"index": 1, "status": 422, "errors": {"sku": ["Такий SKU вже існує"]}}
]
}
Деякі API використовують 207 Multi-Status, але більшість обирає 200 з детальним тілом. Клієнт мусить перевіряти кожен результат - звичайна перевірка статусу відповіді нічого не скаже.
Яку модель обрано - має бути явно в документації і, бажано, в самому API (параметр atomic=true).
Обмеження й безпека:
- максимальний розмір пакета (100-1000 позицій) - перевищення дає 413/422, а не тайм-аут;
- ліміт частоти рахує позиції, а не запити - інакше пакети стають обходом ліміту;
- авторизація кожної позиції - пакет не повинен дозволяти змінити чужі записи серед своїх;
- ідемпотентність (
Idempotency-Key) - повтор пакета після обриву з'єднання не повинен створити дублікати.
Великі пакети - асинхронно: імпорт десятків тисяч позицій приймається як 202 Accepted з ресурсом статусу, обробляється чергою частинами (у Laravel - Bus::batch() з джобами).
Ефективність на сервері: масова вставка (insert() чи upsert() по частинах) замість створення моделей по одній - але тоді не спрацюють події й спостерігачі моделей, і це треба враховувати.
Докладніше в документації: Google AIP-233: пакетне створення
