Как проектировать API, чтобы не ломать клиентов через год

Практически каждое API начинает жить по одному сценарию:

«Сейчас сделаем просто, потом поправим.»

Через год появляется мобильное приложение, партнеры, интеграции, публичный API — и выясняется, что любое изменение превращается в катастрофу.

Проблема не в том, что API меняется. Проблема в том, что оно меняется несовместимо.

1. API — это контракт

Самая распространенная ошибка — считать API отражением структуры базы данных.

GET /users

не означает

SELECT * FROM users

API — это публичный контракт.

Внутри можно полностью переписать архитектуру, но если контракт не изменился — клиент этого даже не заметит.

2. Не возвращайте всё подряд

Плохой пример

{
  "id": 1,
  "password_hash": "...",
  "created_at": "...",
  "updated_at": "...",
  "deleted_at": null,
  "status_id": 2
}

Хороший

{
  "id": 1,
  "name": "John",
  "status": "active"
}

Каждое лишнее поле становится обязательством.

3. Добавлять можно. Удалять нельзя.

Большинство клиентов спокойно переживут появление нового поля

{
  "id": 1,
  "name": "John",
  "avatar": "..."
}

Но удаление старого поля мгновенно ломает интеграции.

Поэтому:

• новые поля — безопасно;
• удаление — почти никогда.

4. Не используйте числовые значения, смысл которых известен только серверу

Плохо

{
    "status": 3
}

Что такое 3?

Лучше

{
    "status": "processing"
}

Или

{
    "status": {
        "code": "processing",
        "title": "В обработке"
    }
}

5. Не заставляйте клиента делать лишние запросы

Вместо

GET /orders

↓

GET /users/15

↓

GET /statuses/2

↓

GET /warehouses/8

Лучше сразу вернуть всё необходимое.

Каждый дополнительный запрос — дополнительная задержка.

6. Никогда не меняйте смысл существующего поля

Самая опасная ошибка.

Сегодня

{
    "price": 100
}

Через год

{
    "price": {
        "value":100,
        "currency":"USD"
    }
}

Формально поле осталось тем же.

Фактически сломались все клиенты.

Если нужна новая структура — добавьте новое поле.

7. Ошибки тоже являются частью API

Плохой ответ

{
    "message":"Ошибка"
}

Хороший

{
    "code":"OUT_OF_STOCK",
    "message":"Товар закончился"
}

Клиент должен принимать решение по коду, а не по тексту.

8. Не верьте, что v2 всё исправит

Очень многие говорят:

Потом сделаем v2.

Через несколько лет оказывается:

• работает v1;
• работает v2;
• половина клиентов на v1;
• половина на v2.

И приходится поддерживать оба.

Версионирование не заменяет хорошее проектирование.

9. Думайте о будущем, но не пытайтесь предугадать всё

Не нужно строить универсальный API на все случаи жизни.

Лучше делать изменения так, чтобы они были совместимы.

Это проще, дешевле и надежнее.

Заключение

Хорошее API — это не то, которое никогда не меняется.

Хорошее API — это то, которое можно развивать годами, не заставляя клиентов переписывать свой код после каждого обновления.