Как проектировать 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/ordersNested 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: Идентификация ресурсов.