Перейти к основному содержимому

Советы по проектированию REST API

1. Множественное число для коллекций​

✅

GET /products
GET /products/{product_id}

❌

GET /product/{product_id}

2. Не используйте глаголы в URL ресурсов​

Использовать HTTP методы для описания операций.

❌


POST /updateuser/{userId} или GET /getusers

✅

PUT /user/{userId}

3. Не добавлять лишние сегменты в путь​

✅

GET /v3/application/listings/{listing_id}

❌

PATCH /v3/application/shops/{shop_id}/listings/{listing_id}

Не пытаться отразить всю модель данных в URL. Если listing_id уникален — shop_id не нужен.

Исключение — если ключ действительно составной:

GET /listings/{listing_id}/options/{option_id}

4. Не добавлять расширения в URL​

❌

GET /users.json

Формат передачи должен определяться через HTTP-заголовки (например, Accept) , не через URL.
✅

GET /users

и HTTP-заголовки настройка заголовков:

Accept: application/json

5. Не возвращать массивы верхнего уровня​

Объект позволяет легко добавить пагинацию и дополнительные поля без поломки обратной совместимости

❌

[{"id":1}, {"id":2}]

✅

{ "data": [{"id":1}, {"id":2}] }

6. Строки для идентификаторов​

Строки гибче: можно объединять, версионировать и переносить данные между базами без конфликтов.
❌

  { "id": 123 }

✅

 { "id": "123" }

7. Добавлять префиксы к ID​

Помогает отличать типы сущностей и уменьшает путаницу при поддержке Примеры:

Stripe: in_1MVpWEJVZPfyS2HyRgVDkwiZ
Shopify: gid://shopify/FulfillmentOrder/1469358604360

8. Не использовать 404 для "не найдено"​

❌

  • 404 Not Found может означать сетевую ошибку или неверный URL
  • Может быть возвращен прокси, балансировщиком нагрузки и т.д.
  • Не позволяет клиенту отличить "ресурс не существует" от "ошибка конфигурации"

✅
Использовать, например, 410 Gone — сервер понял запрос, но объекта нет.
Особенно важно в распределённых системах с повторными операциями (retry)

9. Последовательность​

Одинаковые поля для одинаковых сущностей во всех частях API.
✅ Единообразие в названиях и структуре полей для схожих объектов (например, Address)
❌ Несоответствия полей (country, country_name, country_code) создают путаницу и ошибки

10. Ошибки в структурированном формате​

Позволяет передавать цепочку ошибок и упрощает отладку.
✅

{
  "message": "Access denied",
  "type": "Unauthorized",
  "types": ["Unauthorized", "Security"],
  "cause": { ... }
}

11. Идемпотентность операций​

Идемпотентность = повтор вызова не меняет результат

✅

  • GET, PUT, DELETE — по определению идемпотентны
  • Для POST добавлять идемпотентный ключ: клиент отправляет уникальный ключ в заголовке или теле, а сервер проверяет его уникальность
POST /orders
Idempotency-Key: abc123

Если запрос повторится — сервер вернёт 409 CONFLICT и ID уже созданного ресурса:

{ "message": "Duplicate", "old_id": "ORD123" }

Клиент уверен, что заказ не задублировался

12. ISO8601 для даты и времени​

А также использовать ISO8601 для интервалов и длительностей.
✅ 2023-12-21T11:17:12.34Z
❌ 1703157432340

  • ISO8601 человеко-читаем
  • поддерживается всеми библиотеками
  • работает в UTC

❌Не доверять форматам по умолчанию в языке программирования.
✅ Явно использовать функции для генерации ISO 8601 (например, Date.toISOString() в JavaScript)

13. Не возвращать структуры-словари (map)​

Словари ломают совместимость и неудобны для типизированных языков.

Исключение — простые пары ключ: значение(например, metadata).

✅

{ "data": [{ "id":"KEY1" }, { "id":"KEY2" }] }

❌

{ "KEY1": {...}, "KEY2": {...} }

Материалы​

  1. How to (and how not to) design REST APIs (исходная статья, en)
  2. Идемпотентность в распределённых системах
  3. [12 неочевидных правил проектирования REST API] (https://habr.com/ru/companies/redmadrobot/articles/719222/)
  4. Лучшие практики разработки REST API: 20 советов
  5. [Шпаргалка по проектированию REST API] (https://habr.com/ru/articles/947410/)
  6. 15 важнейших рекомендаций по проектированию REST API
  7. Как разработать идеальный Web API: советы и ошибки на этом пути

Видео​

  1. Как спроектировать хороший api: 20 лучших практик
  2. Как спроектировать REST API
  3. Как писать REST API — 9 правил

Книги​

  1. Паттерны проектирования API - Джей Гивакс
  2. Проектирование веб-API - Арно Лоре