Проєктування REST API для продуктових команд

Коротка відповідь

Будуйте REST навколо ресурсів продукту, визначаючи авторизацію, валідацію, переходи й відмови. Назви методів і гарні URL не компенсують відсутності перевірки власника. Корисний endpoint дозволяє виконати задачу, зрозуміти помилки й безпечно повторити там, де це дозволяє контракт.

Почніть з одного ресурсу й небагатьох операцій. В умовному застосунку активностей сесія належить користувачу й переходить від запису до завершення. Це навчальна модель, окрема від опису WatersportGPS: портфоліо не надає його API чи схему.

Практичні кроки реалізації

Визначте межі ресурсів

Визначте ID, власника чи tenant, змінні й незмінні поля та переходи. Отримуйте користувача з перевіреної сесії; ownerId у body не є авторитетом. Шукайте записи в межах доступу, не сподівайтеся на приховані UI-ідентифікатори. Авторизація потрібна також спискам і експорту.

Свідомо використовуйте семантику методів

GET отримує без запиту зміни стану. POST часто створює чи запускає дію. PUT описує заміну, PATCH — часткову зміну. Ідемпотентність стосується очікуваного ефекту повторів, а не однакових body. DELETE може після першого видалення повертати інший статус зі збереженням очікуваного ефекту.

Зробіть помилки придатними до дії

Поверніть стабільний код, безпечне пояснення та поля за потреби. Розрізняйте хибний ввід, відсутність входу, недостатній дозвіл, відсутній ресурс і конфлікт. Узгодьте відповідь для відсутнього й недоступного запису, щоб не розкривати існування. Не повертайте stack trace, помилки БД, токени чи приватні значення.

Визначте списки та повтори

Обмежте сторінку, визначте стабільне сортування з унікальним додатковим ключем і cursor зі збереженням фільтрів. Offset достатній малим сталим спискам; мінливим часто потрібен cursor. Для створення визначте idempotency key, пов’язаний із користувачем і payload. Заголовок не прибирає дублікати без атомарного збереження сервером.

Приклад реалізації

TypeScript описує контракт відповіді, не повний сервер. Клієнт має явні гілки успіху й помилки. Реалізація потребує runtime-валідації, входу, scoped-запитів і меж розміру.

type SessionSummary = { id: string; status: "recording" | "complete" };
type ApiError = {
  code: "INVALID_INPUT" | "NOT_FOUND" | "CONFLICT";
  message: string;
  requestId: string;
};
type CreateSessionResponse =
  | { ok: true; data: SessionSummary }
  | { ok: false; error: ApiError };

function parsePageSize(raw: string | null): number {
  const value = raw === null ? 20 : Number(raw);
  if (!Number.isInteger(value) || value < 1 || value > 100) {
    throw new Error("Invalid page size");
  }
  return value;
}

Типи описують контракт, але не перевіряють JSON. Перетворіть відмови валідації на узгоджену відповідь і статус. Генеруйте request ID незалежно, лишайте внутрішню діагностику серверу та не включайте приватний ввід в ID.

Компроміси та альтернативи

Ресурсні endpoint зрозумілі для CRUD. Дія завершення сесії може потребувати окремої адреси, коли перевіряє перехід, пише записи й запускає роботу. Не ховайте це в неоднозначному patch. Зберігайте поведінку клієнтів і версіонуйте несумісний контракт, а не кожну зміну коду.

Поширені помилки

• Довіра до user чи tenant ID у body.
• Необмежені списки та довільні вирази сортування.
• Сліпі повтори POST після timeout.
• HTTP 200 для всіх помилок без контракту.
• Перейменування полів без міграції клієнтів.

Контрольний список перед випуском

• ☐ Операції перевіряють вхід і власника.
• ☐ Runtime-схеми й межі відхиляють хибне.
• ☐ Методи, статуси й коди описано.
• ☐ Пагінація має межу й стале сортування.
• ☐ Повтори та конкурентні записи визначено.
• ☐ Сумісність звірено з клієнтами.

Поширені запитання

Чи REST потребує URL кожній таблиці?

Ні. Публічна модель відповідає задачі та доступу. Join і сховище можуть лишатися деталями. Не розкривайте колонки лише через зручність серіалізації всього запису.

Чи клієнт може повторити будь-який збій?

Не без розуміння операції. Втрачена відповідь може йти після успішного запису. Використовуйте семантику й контракт усунення дублікатів, повторюючи лише дозволені відмови обмежено.

Висновок

Перевірте API через повну задачу: успіх, хибний ввід, заборонений доступ, конфлікт і повтор. Узгоджений контракт цих п’яти випадків допомагає оцінити маршрути та фреймворк.

Первинні джерела

• MDN: методи HTTP
• MDN: ідемпотентність
• MDN: статуси HTTP

Пов’язані посібники та приклади

• Тематичний розділ
• Як створити розширення Chrome з Manifest V3
• Структура проєкту розширення Chrome, що масштабується
• Як написати файл manifest.json для Manifest V3
• Каталог проєктів портфоліо