re:re:actable
Урок 022 минуты чтения

Как проектировать REST resources и endpoints?

На этой странице
Кратко

Хороший REST endpoint описывает ресурс существительным, использует HTTP method для действия и остается предсказуемым. В URL лучше избегать глаголов вроде get, create, delete, если действие уже выражено методом.

Вопрос

Как правильно называть REST endpoints? Когда использовать вложенные ресурсы и что делать с действиями, которые не похожи на CRUD?

Базовый CRUD

GET    /users        получить список
POST   /users        создать пользователя
GET    /users/:id    получить пользователя
PATCH  /users/:id    обновить пользователя
DELETE /users/:id    удалить пользователя

Такой API легко читать, тестировать и документировать.

Nested resources

GET  /users/:userId/orders
POST /users/:userId/orders

Nested URL уместен, если ресурс действительно читается в контексте родителя.

Но не стоит делать слишком глубокие пути:

/companies/:companyId/departments/:departmentId/teams/:teamId/users/:userId/tasks/:taskId

Обычно 1-2 уровня вложенности достаточно.

Actions, которые не похожи на CRUD

Иногда действие не укладывается в обычный CRUD.

POST /orders/:id/cancel
POST /users/:id/avatar
POST /reports

Это нормально, если действие является domain operation. Главное - не превращать весь API в /doSomething.

Имена ресурсов

Обычно используют plural nouns:

/users
/orders
/products

Не смешивай стили:

/user
/orders
/ProductList

Что важно помнить

  • Используйте kebab-case в путях (/order-items) и один стиль именования полей в JSON (обычно camelCase для JS-клиентов).
  • Версионирование API: в пути (/api/v1/...) или в header. Ломающие изменения без новой версии ломают старых клиентов.
  • Идентификаторы в URL лучше делать непредсказуемыми (UUID): последовательные id упрощают перебор чужих данных.
  • Фильтры и параметры выборки — в query string, а не в пути: /products?category=books, а не /products/category/books.

Мини-шпаргалка

  • URL должен называть resource.
  • Method должен выражать действие.
  • Используй plural nouns: /users, /orders.
  • Nested resources полезны, но не делай слишком глубокие URL.
  • Domain actions допустимы: /orders/:id/cancel.

Документация

Microsoft: RESTful web API design, MDN: Идентификация ресурсов.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам