Як реалізувати версіонування API в Express.js?

Версійність API в Express.js

Коли ваш API розвивається, вам потрібно вносити зламані зміни без порушення роботи існуючих клієнтів. Версійність API вирішує цю проблему, підтримуючи кілька версій API одночасно.

Стратегії версійності

1. Версійність за URL-шляхом (Найбільш поширена)

const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

GET /api/v1/users → повертає { name: 'John' }
GET /api/v2/users → повертає { firstName: 'John', lastName: 'Doe' }

Плюси: Простота, явність, легкість у тестуванні
Мінуси: Забруднення URL, дублювання коду

2. Версійність за заголовками

app.use('/api/users', (req, res, next) => {
  const version = req.headers['api-version'] || '1';

  switch (version) {
    case '1':
      return v1UserController.getAll(req, res, next);
    case '2':
      return v2UserController.getAll(req, res, next);
    default:
      return res.status(400).json({ error: `Невідома версія API: ${version}` });
  }
});

GET /api/users
Headers: { "Api-Version": "2" }

Плюси: Чисті URL
Мінуси: Складніше виявити, тестувати в браузері

3. Версійність за параметрами запиту

app.get('/api/users', (req, res) => {
  const version = req.query.version || '1';

  if (version === '2') {
    return res.json(getUsersV2());
  }
  return res.json(getUsersV1());
});

GET /api/users?version=2

Рекомендується: URL-шлях з спільною логікою

src/
├── routes/
│   ├── v1/
│   │   ├── index.js
│   │   ├── users.routes.js
│   │   └── products.routes.js
│   └── v2/
│       ├── index.js
│       ├── users.routes.js     ← лише змінені кінцеві точки
│       └── products.routes.js  ← повторно експортує v1, якщо незмінено
├── controllers/
│   ├── v1/
│   └── v2/
└── services/              ← спільна бізнес-логіка

// routes/v2/products.routes.js
// Немає змін з v1 — повторний експорт
module.exports = require('../v1/products.routes');

Заголовки для знецінення

Коли ви знецінюєте версію, інформуйте клієнтів через заголовки:

// Проміжне програмне забезпечення для знеціненого v1
function deprecationWarning(req, res, next) {
  res.set('Deprecation', 'true');
  res.set('Sunset', 'Сб, 01 Чер 2026 00:00:00 GMT');
  res.set('Link', '</api/v2>; rel="successor-version"');
  next();
}

app.use('/api/v1', deprecationWarning, v1Router);

Найкращі практики

Практика	Опис
Почніть з версійності	Додайте `/v1` з самого початку
Підтримуйте максимум 2 версії	Поточна + попередня
Знецінюйте належним чином	Встановіть дати закриття, повідомте користувачів
Діліться бізнес-логікою	Версійність лише для шару API
Документуйте зміни	Журнал змін для кожної версії
Семантична версійність	Основна = зламані зміни, незначна = доповнення

Рекомендація: Використовуйте версійність за URL-шляхом — це найявніша, найпростіша у реалізації стратегія, яка добре працює з інструментами документації API, такими як Swagger. Почніть з /api/v1 з першого дня, навіть якщо спочатку не плануєте версійність.

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

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Дочитали статтю?

Практика завдань