Практичний гайд з дизайну REST API, який переживе нових клієнтів і нові версії: ресурси і статус-коди, помилки за RFC 9457, курсорна пагінація, ключі ідемпотентності, ліміти, OpenAPI і безпечний deprecation. З кодом для Next.js і реальними HTTP-прикладами.
- Опубліковано
- Читання
- 15 хв
- Автор
- Yaroslav Tsarenko

API — це обіцянка. Кожна назва поля, кожен статус-код і кожен формат помилки, які ви випустили, стають контрактом для клієнтів: мобільного застосунку, що оновлюється раз на місяць, інтеграції партнера, яку ніхто не чіпав два роки, вашого ж фронтенду. Змінити ендпоінт легко. Змінити його так, щоб ніхто не зламався, — дорого.
Я пишу бекенди на Node.js і TypeScript з 2021 року, і головне, що я ціную в API, — щоб контракт тримався: інтеграції з провайдерами і вебхуки для e-commerce-студії з Латвії, черги задач для американської платформи замовлень SimplyDepo. Нижче 12 правил, до яких я щоразу повертаюся, з кодом для Next.js route handlers, реальними HTTP-запитами і відповідями та посиланнями на стандарти, де вони вже є.
Чому API старіє погано
API рідко ламається одним великим рішенням. Воно старіє від дрібниць: одне поле в camelCase, сусіднє в snake_case; помилка в одному ендпоінті приходить як { "error": "..." }, а в іншому як { "message": "..." }; список віддає всі записи, бо на старті їх було двадцять. Кожна така дрібниця перетворюється на кілька рядків адаптерного коду в кожному клієнті — назавжди.
Хороша новина: майже для кожної з цих дрібниць уже є стандарт або усталена практика. HTTP-семантику описує RFC 9110, формат помилок — RFC 9457, deprecation — RFC 9745 і RFC 8594, а для ключів ідемпотентності і заголовків лімітів є активні чернетки IETF. Не треба вигадувати своє — достатньо послідовно взяти готове.
Правила 1–2: ресурси, методи і статус-коди
Правило 1. Іменники в URL, дії — в методах
API з ендпоінтами POST /createOrder, POST /updateOrder, POST /getOrders виглядає як набір функцій. API з POST /orders, PATCH /orders/{id}, GET /orders виглядає як система, і клієнт може вгадати наступний URL, не відкриваючи документацію.
Кілька правил, що прибирають більшість суперечок:
- Колекції у множині:
/orders,/customers,/orders/{id}/items. - Вкладеність не глибша за один рівень.
/customers/{id}/orders— нормально,/customers/{id}/orders/{id}/items/{id}/notes— ні: дайте нотаткам власний ресурс. - Дії, що не лягають у CRUD, оформлюйте як підресурс:
POST /orders/{id}/cancellationзамістьPOST /orders/{id}/cancel. Скасування стає сутністю з часом, автором і причиною, і його можна прочитати черезGET. - Ідентифікатори непрозорі для клієнта:
ord_7f3a, а не автоінкремент, з якого видно, скільки у вас замовлень.
Правило 2. Метод і статус-код несуть сенс
HTTP вже дає вам семантику безкоштовно. За RFC 9110, GET, HEAD і OPTIONS безпечні, а PUT і DELETE ідемпотентні: повтор не змінює результату. POST і PATCH такої гарантії не мають — саме тому для них знадобиться правило 7.
Статус-коди — це не прикраса. Проксі, CDN, моніторинг і SDK клієнтів читають саме код, а не тіло. Якщо API відповідає 200 з { "error": "not found" }, усі ці інструменти сліпнуть: кеш збереже помилку, графік помилок покаже нуль.
| Ситуація | Код | Що ще віддати |
|---|---|---|
| Успіх з тілом | 200 OK |
ресурс |
| Ресурс створено | 201 Created |
Location на новий ресурс |
| Успіх без тіла | 204 No Content |
нічого |
| Задачу прийнято у фон | 202 Accepted |
посилання на статус задачі |
| Запит не розібрати | 400 Bad Request |
problem details |
| Немає автентифікації | 401 Unauthorized |
WWW-Authenticate |
| Немає прав | 403 Forbidden |
problem details |
| Ресурсу немає для цього клієнта | 404 Not Found |
problem details |
| Конфлікт стану або версії | 409 Conflict |
що саме конфліктує |
| Дані коректні, але не проходять правила | 422 Unprocessable Content |
помилки по полях |
| Забагато запитів | 429 Too Many Requests |
Retry-After |
| Помилка сервера | 500 |
instance для пошуку в логах |
Про 202: якщо операція може тривати довше за кілька секунд, не тримайте з'єднання. Поверніть 202 Accepted з посиланням на ресурс задачі, а роботу віддайте воркеру. Саме так у SimplyDepo розсилку сповіщень перенесли в чергу з повторами і dead-letter, і ендпоінти, які бачать користувачі, перестали на неї чекати. Як влаштувати таку чергу, я детально розписав у гайді з черг задач у Node.js.
Правило 3: один контракт помилок (RFC 9457)
Помилка — теж частина API, і найчастіше саме вона в кожному ендпоінті своя. Не вигадуйте конверт: RFC 9457 описує формат problem details з типом вмісту application/problem+json. Він замінив RFC 7807 у 2023 році.
Обов'язкових полів немає, але на практиці потрібні п'ять: type (URI, на який клієнт робить switch), title (коротко для людини), status, detail (що сталося саме тут) і instance (ідентифікатор цього випадку для пошуку в логах). Решту можна додати як розширення, наприклад errors для помилок по полях.
Хелпер, який я кладу в кожен проєкт:
type FieldError = { pointer?: string; parameter?: string; detail: string };
type Problem = { type: string; title: string; status: number; detail?: string; instance?: string; errors?: FieldError[] };
export function problem(p: Problem, headers: Record<string, string> = {}) {
return Response.json(p, { status: p.status, headers: { "content-type": "application/problem+json", ...headers } });
}Помилка валідації в такому форматі виглядає так:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/validation",
"title": "Request body is invalid",
"status": 422,
"errors": [{ "pointer": "/amount", "detail": "must be a positive number" }]
}Три правила, що роблять цей контракт корисним. Клієнт розгалужується лише за type, ніколи за текстом title — текст ви захочете змінити. type веде на сторінку документації з поясненням і способом виправлення. А 500 ніколи не віддає стек чи текст помилки бази: лише instance, за яким ви знайдете деталі у своїх логах.
Правило 4: версіонування
Версія потрібна з першого дня, навіть якщо друга з'явиться через три роки. Додати /v1 пізніше означає змінити кожен URL у кожному клієнті.
Два робочі підходи:
- Версія в URL (
/v1/orders). Видно в логах, у кеші, в адресному рядку браузера. Я обираю її для більшості продуктів. - Версія в заголовку (
Accept: application/vnd.example.v2+jsonабо власний заголовок). Чисті URL, але складніше дебажити і легко забути при кешуванні: тоді потрібенVary.
Важливіше за спосіб — правило, коли піднімати мажорну версію. Відповідь: лише для змін, що ламають наявних клієнтів. Усе інше додається в поточну версію.
Безпечно: додати нове необов'язкове поле у відповідь, новий ендпоінт, нове значення в запит, яке можна не передавати. Ламає: перейменувати чи видалити поле, змінити його тип, зробити необов'язкове поле обов'язковим, змінити сенс статус-коду, додати нове значення в enum, на який клієнти роблять вичерпний switch. Останнє підступне, тому в документації одразу пишіть: «невідомі значення ігноруйте».
Правила 5–6: пагінація, фільтри, сортування
Правило 5. Курсор замість offset
?page=3&limit=20 перетворюється на OFFSET 40 LIMIT 20. Це має дві проблеми. Перша — швидкість: щоб віддати тисячну сторінку, база все одно читає і відкидає всі попередні рядки. Друга — коректність: якщо між запитами з'явилося нове замовлення, весь список зсувається, і клієнт бачить один запис двічі або пропускає інший.
Курсорна пагінація запам'ятовує не номер сторінки, а останній побачений запис. Курсор — непрозорий рядок, у якому закодовано ключ сортування і id для однозначності:
type Row = { id: string; createdAt: string };
export const encodeCursor = (r: Row) => Buffer.from(JSON.stringify([r.createdAt, r.id])).toString("base64url");
export const decodeCursor = (c: string) => {
const [createdAt, id] = JSON.parse(Buffer.from(c, "base64url").toString()) as [string, string];
return { createdAt, id };
};Route handler списку замовлень у Next.js з фільтром, обмеженням limit і курсором:
import { pool } from "@/lib/db";
import { problem } from "@/lib/problem";
import { decodeCursor, encodeCursor } from "@/lib/cursor";
const STATUSES = ["pending", "paid", "shipped", "cancelled"];
export async function GET(req: Request) {
const url = new URL(req.url);
const limit = Math.min(Math.max(Number(url.searchParams.get("limit")) || 20, 1), 100);
const statuses = url.searchParams.getAll("status");
const unknown = statuses.find((s) => !STATUSES.includes(s));
if (unknown)
return problem({
type: "https://api.example.com/problems/validation",
title: "Query is invalid",
status: 400,
errors: [{ parameter: "status", detail: `unknown value "${unknown}"` }],
});
const raw = url.searchParams.get("cursor");
const after = raw ? decodeCursor(raw) : null;
const { rows } = await pool.query(
`select id, status, total, created_at from orders
where ($1::text[] is null or status = any($1))
and ($2::timestamptz is null or (created_at, id) < ($2::timestamptz, $3::text))
order by created_at desc, id desc
limit $4`,
[statuses.length ? statuses : null, after?.createdAt ?? null, after?.id ?? null, limit + 1],
);
const page = rows.slice(0, limit);
const last = page.at(-1);
const next_cursor = rows.length > limit && last ? encodeCursor({ id: last.id, createdAt: last.created_at.toISOString() }) : null;
return Response.json({ data: page, next_cursor });
}Запит на один рядок більше за limit дає змогу дізнатися, чи є наступна сторінка, без окремого count(*). Під цей запит потрібен індекс create index on orders (created_at desc, id desc). Відповідь:
GET /v1/orders?status=paid&limit=2 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{ "id": "ord_7f3b", "status": "paid", "total": 4900, "created_at": "2026-11-02T10:02:00.000Z" },
{ "id": "ord_7f3a", "status": "paid", "total": 12000, "created_at": "2026-11-02T09:15:00.000Z" }
],
"next_cursor": "WyIyMDI2LTExLTAyVDA5OjE1OjAwLjAwMFoiLCJvcmRfN2YzYSJd"
}Offset має право на життя в невеликих адмінських таблицях, де людина хоче перейти на п'яту сторінку. Для стрічок, експортів і всього, що читає інша програма, — курсор.
Правило 6. Фільтри і сортування за одним синтаксисом
- Оберіть один формат множинних значень:
?status=paid&status=shippedабо?status=paid,shipped. Не змішуйте їх у різних ендпоінтах. - Сортування одним параметром:
?sort=-created_at(мінус означає спадання). Дозволені поля — зі списку, а не будь-яка колонка. - Невідомий фільтр чи поле сортування — це
400з поясненням, а не тихе ігнорування. Інакше клієнт з одруківкою отримує нефільтрований список і думає, що все працює. - Кожен фільтр, який ви відкрили, має спиратися на індекс. Як знайти повільні запити через
EXPLAIN ANALYZE, я показував у гайді з оптимізації PostgreSQL у Node.js.
Правило 7: ключі ідемпотентності
Мережа ненадійна. Клієнт надіслав POST /orders, сервер створив замовлення, а відповідь загубилася. Клієнт повторює запит — і тепер замовлень два. Для GET і PUT повтор безпечний за визначенням, для POST — ні.
Рішення — заголовок Idempotency-Key. Клієнт генерує випадковий ключ (зазвичай UUID) на кожну логічну операцію і передає його в усіх повторах. Сервер запам'ятовує результат під цим ключем і на повтор віддає ту саму відповідь. Станом на листопад 2026 року це активна чернетка IETF (версія 08 від 22 жовтня), ще не RFC, але поведінка вже усталена. Чернетка радить три відповіді: 400, якщо ключ обов'язковий і його немає; 409, якщо перший запит з цим ключем ще виконується; 422, якщо ключ повторно використали з іншим тілом. Сервер має також опублікувати, скільки зберігає ключі.
Ось обгортка для route handler. Для наочності ключі тут у Map; у продакшені це таблиця в PostgreSQL з унікальним ключем або Redis з TTL:
import { createHash } from "node:crypto";
import { problem } from "@/lib/problem";
type Stored = { fingerprint: string; status: number; body: string } | { fingerprint: string; pending: true };
const keys = new Map<string, Stored>();
const P = "https://api.example.com/problems";
export async function withIdempotency(req: Request, run: (body: unknown) => Promise<Response>) {
const key = req.headers.get("idempotency-key");
if (!key) return problem({ type: `${P}/idempotency-key-missing`, title: "Idempotency-Key header is required", status: 400 });
const raw = await req.text();
const fingerprint = createHash("sha256").update(raw).digest("hex");
const seen = keys.get(key);
if (seen && seen.fingerprint !== fingerprint)
return problem({ type: `${P}/idempotency-key-reused`, title: "Key was used with a different body", status: 422 });
if (seen && "pending" in seen)
return problem({ type: `${P}/request-in-progress`, title: "The original request is still running", status: 409 }, { "retry-after": "1" });
if (seen) return new Response(seen.body, { status: seen.status, headers: { "content-type": "application/json", "idempotent-replayed": "true" } });
keys.set(key, { fingerprint, pending: true });
try {
const res = await run(JSON.parse(raw));
if (res.status < 500) keys.set(key, { fingerprint, status: res.status, body: await res.clone().text() });
else keys.delete(key);
return res;
} catch (err) {
keys.delete(key);
throw err;
}
}Я прогнав чотири запити до POST /v1/orders: ключ k1 з { "amount": 4900 }, той самий ключ і тіло ще раз, той самий ключ з { "amount": 5000 } і ключ k2 з від'ємною сумою. Результат (Node.js 25):
201 - {"id":"ord_80739a58","amount":4900,"status":"pending"}
201 true {"id":"ord_80739a58","amount":4900,"status":"pending"}
422 - {"type":"https://api.example.com/problems/idempotency-key-reused","title":"Key was used with a different body","status":422}
422 - {"type":"https://api.example.com/problems/validation","title":"Request body is invalid","status":422,"errors":[{"pointer":"/amount","detail":"must be a positive number"}]}Повтор віддав те саме замовлення з тим самим id, а не створив нове. Відповіді 5xx я не зберігаю: клієнт має право повторити запит і отримати шанс на успіх. У продакшені запис ключа і створення замовлення варто робити в одній транзакції. У PostgreSQL 19 для цього зручно використати INSERT ... ON CONFLICT DO SELECT, який атомарно повертає наявний рядок, — я розбирав його в гайді з оновлення до PostgreSQL 19. Той самий принцип працює і для вхідних вебхуків: подія з тим самим id від провайдера має оброблятися рівно один раз.
Правила 8–9: ліміти запитів і автентифікація
Правило 8. Ліміти — частина контракту
Ліміти захищають не лише від атак. Найчастіше вони рятують від власного клієнта, який у циклі робить fetch для кожного з десяти тисяч id. Клієнт має бачити, скільки запитів у нього лишилося, а не дізнаватися про це з 429.
Чернетка IETF про заголовки лімітів (версія 11, травень 2026) пропонує два поля: RateLimit-Policy описує квоту, RateLimit — поточний залишок. Багато API досі віддають старі X-RateLimit-*; якщо у вас вони вже є, не прибирайте їх, а додайте нові поруч.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=0;t=17
Retry-After: 17
{
"type": "https://api.example.com/problems/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Limit is 100 requests per 60 seconds for this API key."
}Ліміт рахуйте за ключем клієнта, а не лише за IP: за одним офісним NAT можуть сидіти десятки людей. І давайте окремі ліміти дорогим ендпоінтам — пошуку, експорту, генерації звітів.
Правило 9. Автентифікація і доступ до кожного об'єкта
- Лише HTTPS. Токени в заголовку
Authorization: Bearer ..., ніколи в query string: URL потрапляють у логи проксі й історію браузера. 401означає «хто ви?» і за RFC 9110 має міститиWWW-Authenticate.403означає «я знаю, хто ви, але не можна».- Якщо сам факт існування ресурсу — секрет (чуже замовлення, чужий рахунок), відповідайте
404, а не403. - Перевіряйте право доступу до конкретного об'єкта в кожному обробнику. Те, що користувач увійшов, не означає, що
GET /orders/ord_7f3aналежить йому. Це перший пункт у OWASP API Security Top 10: broken object level authorization.
Останній пункт я перевіряю першим, коли беру чужий код. У проєкті AllShip AI я проводив аудит авторизації 109 точок входу, перш ніж об'єднати три застосунки в один.
Правила 10–11: однакові форми і контракт спершу
Правило 10. Одна форма для всього
Клієнт вчиться працювати з вашим API на першому ендпоінті. Усі наступні мають поводитися так само:
- Один регістр полів. Або
created_atскрізь, абоcreatedAtскрізь. Ніколи обидва в одній відповіді. - Дати — рядки ISO 8601 в UTC:
2026-11-03T10:00:00Z. Не Unix-час в одному місці і локальний час в іншому. - Гроші — ціле число в мінімальних одиницях плюс код валюти:
{ "total": 4900, "currency": "EUR" }. Число з плаваючою комою для грошей рано чи пізно дасть0.30000000000000004. - Списки завжди в однаковому конверті:
{ "data": [...], "next_cursor": ... }. Окремий ресурс — без конверта. - Порожнє значення —
null, а не порожній рядок в одному місці і відсутнє поле в іншому.
Правило 11. Спершу контракт, потім код
Опишіть API в OpenAPI до того, як писати обробники. Тоді контракт — це файл у репозиторії, який проходить код-рев'ю, а не побічний продукт коду. Фрагмент для ендпоінту з цієї статті:
openapi: 3.1.1
info: { title: Orders API, version: 1.0.0 }
paths:
/v1/orders:
post:
parameters:
- { name: Idempotency-Key, in: header, required: true, schema: { type: string } }
responses:
"201": { description: Created, content: { application/json: { schema: { $ref: "#/components/schemas/Order" } } } }
"422": { description: Invalid body, content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } } }
components:
schemas:
Order:
type: object
required: [id, amount, status]
properties: { id: { type: string }, amount: { type: integer }, status: { type: string } }
Problem:
type: object
properties: { type: { type: string }, title: { type: string }, status: { type: integer }, detail: { type: string } }Що дає контракт у репозиторії: типи для фронтенду генеруються з нього (наприклад, openapi-typescript), документація збирається на кожному деплої і не відстає від коду, а в CI можна порівнювати специфікацію з основною гілкою інструментом на кшталт oasdiff і блокувати злиття, якщо зміна ламає клієнтів. Так правило 4 перестає залежати від пильності рев'юера.
Правило 12: як прибирати старе (deprecation)
Рано чи пізно ендпоінт треба прибрати. Найгірший спосіб — вимкнути його в п'ятницю й чекати листів. Для цього є два стандартні заголовки: Deprecation з RFC 9745 (березень 2025) повідомляє, що ресурс застарів, а Sunset з RFC 8594 — коли він перестане відповідати. Дата Sunset не може бути раніше за Deprecation.
GET /v1/orders/ord_7f3a HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1798761599
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-to-v2>; rel="deprecation"@1798761599 — це 31 грудня 2026 року, 23:59:59 UTC у форматі Unix-часу, як вимагає RFC 9745. Клієнтські SDK можуть читати ці заголовки й писати попередження в логи, а ви бачите у своїх логах, хто досі звертається до старого ендпоінту.
- день 0Нова версія поручv2 працює паралельно з v1
- день 0ОголошенняDeprecation, Sunset і посилання на гайд
- щомісяцяХто ще на v1логи за ключами клієнтів, листи власникам
- за місяць до SunsetПробні вимкненнякороткі вікна з 410 на staging і в продакшені
- дата з заголовкаSunsetv1 відповідає 410 Gone з посиланням на v2
Після Sunset старий ендпоінт краще відповідати 410 Gone з problem details і посиланням на нову версію, ніж просто зникнути з 404: так помилка в клієнта сама пояснює, що робити.
Приклад: редизайн API замовлень
Зберемо все разом на типовому API, яке виросло без правил.
| Було | Стало | Правило |
|---|---|---|
POST /createOrder |
POST /v1/orders з Idempotency-Key, 201 і Location |
1, 2, 7 |
POST /getOrders з { "page": 3 } |
GET /v1/orders?status=paid&cursor=... |
1, 5, 6 |
POST /cancelOrder |
POST /v1/orders/{id}/cancellation |
1 |
200 з { "success": false, "msg": "..." } |
4xx з application/problem+json |
2, 3 |
userId, created_at, Total в одній відповіді |
snake_case скрізь, гроші в центах |
10 |
| звіт генерується 40 секунд у запиті | 202 Accepted і GET /v1/report-jobs/{id} |
2 |
| документація у вікі | OpenAPI у репозиторії, перевірка в CI | 11 |
Порядок міграції важливий. Нові ендпоінти з'являються поруч зі старими під /v1, фронтенд і інтеграції переходять поступово, старі отримують Deprecation і Sunset. Жоден клієнт не мусить оновлюватися в один день із сервером.
Чек-лист перед релізом
| Перевірка | Як | Тривожний знак |
|---|---|---|
| URL — іменники | пройтися по списку маршрутів | дієслова в шляху |
| Статус-коди | тести на кожен 4xx |
200 з помилкою в тілі |
| Помилки | один хелпер problem() |
різні формати в різних модулях |
| Версія | префікс або заголовок з першого дня | URL без версії |
| Списки | курсор і максимальний limit |
список без обмеження |
| Фільтри | список дозволених полів, індекси | невідомі параметри ігноруються |
| Ідемпотентність | Idempotency-Key на POST, що створюють |
повтор створює дублікат |
| Ліміти | 429, Retry-After, заголовки квоти |
ліміту немає зовсім |
| Доступ | перевірка власника в кожному обробнику | GET чужого id повертає дані |
| Форма відповідей | лінтер схеми, один регістр | camelCase поруч із snake_case |
| Контракт | OpenAPI у репозиторії, diff у CI | документація у вікі |
| Deprecation | Deprecation, Sunset, логи старих викликів |
ендпоінти вимикають без попередження |
Що зробити цього тижня
Не треба переписувати все API. Почніть з двох речей, які дають найбільше за найменші гроші: один формат помилок за RFC 9457 і Idempotency-Key на ендпоінтах, що створюють записи. Далі — OpenAPI-файл і перевірка в CI, яка не пропустить зміну, що ламає клієнтів. Решта правил додається поступово, з кожним новим ендпоінтом.
Якщо у вас є API, яке працює, але кожна нова інтеграція з ним коштує тиждень адаптерів, або ви плануєте бекенд для нового продукту на Next.js і Node.js, — напишіть. Подивлюся на контракт і скажу, що виправляв би першим.
Було корисно?
– вподобань · – переглядів
Часті запитання
Яку пагінацію обрати для REST API: offset чи cursor?
Для стрічок і списків, що часто оновлюються, — курсорну: вона не дублює і не губить записи, коли між запитами з'являються нові рядки, і працює однаково швидко на першій і на тисячній сторінці. Offset лишайте для невеликих адмінських таблиць, де потрібен перехід на конкретну сторінку.
Що таке RFC 9457 і чим він відрізняється від RFC 7807?
RFC 9457 — стандарт формату помилок HTTP API (problem details) з типом application/problem+json і полями type, title, status, detail, instance. Він замінив RFC 7807 у 2023 році: формат сумісний, але уточнено роботу з кількома помилками одразу і додано спільний реєстр типів проблем.
Чи є Idempotency-Key офіційним стандартом?
Ще ні. Станом на листопад 2026 року це активний Internet-Draft робочої групи IETF httpapi (версія 08 від 22 жовтня 2026). Але сам заголовок і поведінка — повтор із тим самим ключем повертає ту саму відповідь — давно стали звичною практикою публічних API.
Як версіонувати REST API: в URL чи в заголовку?
Обидва варіанти робочі. Версія в URL (/v1/orders) простіша для логів, кешів і дебагу в браузері, тому для більшості продуктів я обираю її. Важливіше інше: мажорна версія потрібна лише для змін, що ламають клієнтів, а все інше додається без нової версії.
Який статус-код повертати для помилок валідації: 400 чи 422?
400 — коли запит не вдалося розібрати: зламаний JSON, неправильний тип вмісту. 422 Unprocessable Content — коли JSON коректний, але значення не проходять правила: від'ємна сума, неіснуючий статус. Головне — обрати одне правило і дотримуватися його в усьому API.