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

Коли API потрібні пакетні (batch) ендпойнти і як їх проєктувати?

Пакетний ендпойнт виконує багато однотипних операцій одним запитом: імпорт тисячі товарів, позначення 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: пакетне створення

Перевір себе

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

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