Skip to content

Практичний гайд з дизайну 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 для пошуку в логах
Який статус-код повернутиЗапит можна розібрати?ні400 Bad RequestтакВідомо, хто клієнт?ні401 UnauthorizedтакРесурс існує для цього клієнта?ні404 Not FoundтакКлієнт має право на дію?ні403 ForbiddenтакДані проходять правила?ні422 UnprocessableтакСтан дозволяє операцію?ні409 ConflictтакУспіх: 200 · 201 · 202 · 204

Про 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 для помилок по полях.

Хелпер, який я кладу в кожен проєкт:

ts
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
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.

Важливіше за спосіб — правило, коли піднімати мажорну версію. Відповідь: лише для змін, що ламають наявних клієнтів. Усе інше додається в поточну версію.

Безпечно: та сама версіяЛамає клієнтів: нова версіянове поле у відповідіновий ендпоінтнеобов'язковий параметрновий заголовок відповідібільший максимум limitперейменувати чи видалити полезмінити тип полязробити поле обов'язковимзмінити сенс статус-кодунове значення в закритому enum

Безпечно: додати нове необов'язкове поле у відповідь, новий ендпоінт, нове значення в запит, яке можна не передавати. Ламає: перейменувати чи видалити поле, змінити його тип, зробити необов'язкове поле обов'язковим, змінити сенс статус-коду, додати нове значення в enum, на який клієнти роблять вичерпний switch. Останнє підступне, тому в документації одразу пишіть: «невідомі значення ігноруйте».

Правила 5–6: пагінація, фільтри, сортування

Правило 5. Курсор замість offset

?page=3&limit=20 перетворюється на OFFSET 40 LIMIT 20. Це має дві проблеми. Перша — швидкість: щоб віддати тисячну сторінку, база все одно читає і відкидає всі попередні рядки. Друга — коректність: якщо між запитами з'явилося нове замовлення, весь список зсувається, і клієнт бачить один запис двічі або пропускає інший.

OFFSET 3 LIMIT 3Сторінка 1EDCНове замовленняFСторінка 2CBAC вдругеOFFSET 10000 читає 10 020 рядківКурсор після CСторінка 1EDCНове замовленняFСторінка 2BAбез дублівкурсор читає 21 рядок з індексу

Курсорна пагінація запам'ятовує не номер сторінки, а останній побачений запис. Курсор — непрозорий рядок, у якому закодовано ключ сортування і id для однозначності:

ts
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 і курсором:

ts
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). Відповідь:

http
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, якщо ключ повторно використали з іншим тілом. Сервер має також опублікувати, скільки зберігає ключі.

КлієнтAPIСховище ключівБаза замовлень1POST /v1/orders, ключ k12k1: у роботі + хеш тіла3insert order4k1: 201 + тіло відповіді5відповідь загубилась у ме…6повтор, той самий ключ k17знайдено k1, хеш збігаєть…8той самий 201, без нового…
Повтор запиту з тим самим Idempotency-Key: замовлення створюється один раз

Ось обгортка для route handler. Для наочності ключі тут у Map; у продакшені це таблиця в PostgreSQL з унікальним ключем або Redis з TTL:

ts
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):

text
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
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 до того, як писати обробники. Тоді контракт — це файл у репозиторії, який проходить код-рев'ю, а не побічний продукт коду. Фрагмент для ендпоінту з цієї статті:

yaml
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.

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

  1. день 0
    Нова версія поручv2 працює паралельно з v1
  2. день 0
    ОголошенняDeprecation, Sunset і посилання на гайд
  3. щомісяця
    Хто ще на v1логи за ключами клієнтів, листи власникам
  4. за місяць до Sunset
    Пробні вимкненнякороткі вікна з 410 на staging і в продакшені
  5. дата з заголовка
    Sunsetv1 відповідає 410 Gone з посиланням на v2
Як прибрати застарілий ендпоінт, нікого не зламавши

Після Sunset старий ендпоінт краще відповідати 410 Gone з problem details і посиланням на нову версію, ніж просто зникнути з 404: так помилка в клієнта сама пояснює, що робити.

Приклад: редизайн API замовлень

Зберемо все разом на типовому API, яке виросло без правил.

БулоСталоPOST /createOrderPOST /v1/orders + Idempotency-KeyPOST /getOrders { page: 3 }GET /v1/orders?cursor=…POST /cancelOrderPOST /v1/orders/{id}/cancellation200 { success: false }422 application/problem+jsonзвіт 40 с у запиті202 + /v1/report-jobs/{id}
Було Стало Правило
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, — напишіть. Подивлюся на контракт і скажу, що виправляв би першим.

Було корисно?

– вподобань · – переглядів

LinkedInXTelegramFacebook
Потрібно таке для вашого продукту?Розробка на 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.