Gymterview
junior

Каковы лучшие практики проектирования URI?

URI в REST API должны быть предсказуемыми, читаемыми и отражать структуру ресурсов, а не операции над ними.

  1. Используйте существительные, а не глаголы:
Пример
GET  /api/users          (правильно)
GET  /api/getUsers       (неправильно)
POST /api/createUser     (неправильно)
  1. Используйте множественное число для коллекций:
Пример
/api/users               (правильно)
/api/users/42             (правильно)
/api/user                 (неправильно)
  1. Используйте вложенность для связанных ресурсов (не более 2-3 уровней):
Пример
GET /api/users/42/orders       — заказы пользователя 42
GET /api/users/42/orders/7     — заказ 7 пользователя 42

/api/users/42/orders/7/items/3/reviews   (неправильно — слишком глубоко)
/api/order-items/3/reviews               (правильно)
  1. Используйте дефисы для разделения слов:
Пример
/api/order-items          (правильно)
/api/orderItems           (неправильно)
/api/order_items          (неправильно)

  1. Используйте строчные буквы.

  2. Не используйте расширения файлов. Формат определяется через заголовок Accept.

  3. Используйте query-параметры для фильтрации, сортировки и пагинации:

Пример
GET /api/users?status=active&sort=name&page=2&size=20
  1. Для действий вне CRUD используйте подресурсы-глаголы:
Пример
POST /api/users/42/activate
POST /api/orders/7/cancel

  1. Используйте префикс версии (/api/v1/users).

  2. Всегда используйте префикс /api.

На собеседовании: интервьюер ожидает знания основных правил: существительные, множественное число, дефисы, строчные буквы. Частая ошибка — использовать глаголы в URI (POST /api/createUser) или camelCase (/api/orderItems).

#rest