Версіювання API

Навчитеся версіонувати API, підтримувати сумісність клієнтів і безпечно розвивати контракти ресурсів.

Навіщо версіонувати API

API є контрактом між сервером і клієнтами. Контракт описує:

доступні маршрути;
формат запитів;
формат відповідей;
типи та обов’язковість полів;
HTTP-коди;
правила обробки помилок;
семантику операцій.

Зміна контракту може вплинути не лише на ваш frontend, а й на мобільні застосунки, зовнішніх партнерів, інтеграції та скрипти клієнтів.

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

Наприклад, зміна назви поля:

json

{
  "name": "Олена Коваль"
}

javascript

const http = require("node:http");
const { URL } = require("node:url");

const users = [
  {
    id: "user-1",
    firstName: "Олена",
    lastName: "Коваль",
    email: "olena@example.com",
    createdAt: "2026-01-15T10:00:00.000Z"
  },
  {
    id: "user-2",
    firstName: "Андрій",
    lastName: "Мельник",
    email: "andrii@example.com",
    createdAt: "2026-02-20T12:30:00.000Z"
  }
];

function findUserById(id) {
  return users.find((user) => user.id === id);
}

function toV1User(user) {
  return {
    id: user.id,
    name: `${user.firstName} ${user.lastName}`,
    email: user.email
  };
}

function toV2User(user) {
  return {
    id: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    createdAt: user.createdAt
  };
}

function sendJson(response, statusCode, body, headers = {}) {
  response.writeHead(statusCode, {
    "Content-Type": "application/json; charset=utf-8",
    ...headers
  });

  response.end(JSON.stringify(body));
}

function sendNotFound(response) {
  sendJson(response, 404, {
    error: {
      code: "NOT_FOUND",
      message: "Ресурс не знайдено"
    }
  });
}

function handleUsers(request, response, version, userId) {
  const toRepresentation = version === "v1" ? toV1User : toV2User;

  if (request.method !== "GET") {
    sendJson(
      response,
      405,
      {
        error: {
          code: "METHOD_NOT_ALLOWED",
          message: "Метод не підтримується"
        }
      },
      {
        Allow: "GET"
      }
    );

    return;
  }

  if (userId) {
    const user = findUserById(userId);

    if (!user) {
      sendNotFound(response);
      return;
    }

    const headers =
      version === "v1"
        ? {
            // Власні заголовки дозволяють клієнтам побачити план міграції.
            "X-API-Deprecated": "true",
            "X-API-Sunset": "2027-01-01"
          }
        : {};

    sendJson(response, 200, toRepresentation(user), headers);
    return;
  }

  sendJson(response, 200, {
    data: users.map(toRepresentation),
    meta: {
      count: users.length
    }
  });
}

const server = http.createServer((request, response) => {
  const url = new URL(request.url, `http://${request.headers.host}`);
  const segments = url.pathname.split("/").filter(Boolean);

  // Очікувані адреси: /api/v1/users та /api/v2/users.
  if (
    segments.length >= 3 &&
    segments[0] === "api" &&
    ["v1", "v2"].includes(segments[1]) &&
    segments[2] === "users" &&
    segments.length <= 4
  ) {
    handleUsers(request, response, segments[1], segments[3]);
    return;
  }

  sendNotFound(response);
});

server.listen(3000, () => {
  console.log("API запущено на http://localhost:3000");
});

text

запит клієнта
    ↓
маршрутизація версії
    ↓
спільна бізнес-логіка
    ↓
доменна модель
    ↓
адаптер v1 або v2
    ↓
HTTP-відповідь

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Запит містить некоректні дані",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}

Версіювання API

Навіщо версіонувати API

Сумісність клієнтів

Зворотна сумісність

Пряма сумісність

Які зміни є несумісними

Які зміни зазвичай сумісні

Стратегії версіювання

Версія в URL

Версія через заголовок

Версія через query-параметр

Версіювання в Node.js

Спільна доменна модель і адаптери

Життєвий цикл версії

Еволюція ресурсів

Додавання полів

Перейменування полів

Enum-значення

Поля з датами та числами

Версія не замінює міграцію даних

Контрактні тести

Пагінація як частина контракту

Помилки також є контрактом

Коли створювати нову версію

Практичний процес випуску нової версії

Типові помилки

Версіювання лише в назві документації

Змішування форматів у межах однієї версії

Видалення старих полів без перехідного періоду

Дублювання всієї бізнес-логіки

Відсутність плану завершення підтримки

Перевірка лише успішних запитів

Зміна семантики під тим самим ім’ям поля

Summary