Ресурсно-ориентированный REST API: как проектировать URL без глаголов

Когда вы открываете документацию к чужому API и видите эндпоинт /users/create, внутри что-то щелкает. Это не просто стиль, это сигнал о том, что разработчик думал о действии, а не о данных. Ресурсно-ориентированный подход в REST API is архитектурный стиль, где URI идентифицируют ресурсы (сущности), а HTTP-методы описывают операции над ними. Такой подход делает предсказуемым поведение системы для любого клиента, от мобильного приложения до интеграции с CRM.

Почему глаголы ломают логику

Представьте, что у вас есть сервис управления заказами. Если вы используете глаголы, список эндпоинтов превращается в меню действий:

• /orders/get
• /orders/list
• /orders/update
• /orders/delete

Здесь проблема в масштабируемости. Что будет, если нам нужно получить заказы только с фильтром по статусу «оплачено»? Добавим новый глагол? /orders/getPaid? А если нужен экспорт в CSV? /orders/exportCsv. С каждым новым требованием URL становится все длиннее и менее стандартизировым.

В ресурсной модели мы смотрим на объект. Заказ - это ресурс. У него есть состояние (ID, сумма, статус). Чтобы получить список заказов, мы используем метод GET на коллекцию /orders. Чтобы изменить один, используем PATCH или PUT на конкретный ресурс /orders/{id}. Глагол уже встроен в протокол HTTP, поэтому повторять его в адресе избыточно и вредно для кэширования.

Базовые правила построения URI

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

1. Используйте существительные во множественном числе. Не /user, а /users. Не /order, а /orders. Это унифицирует работу с коллекциями.
2. Разделяйте уровни вложенности слешами. Если у пользователя есть адреса, правильный путь - /users/{userId}/addresses. Избегайте точек в именах ресурсов, они зарезервированы для версий API (например, v1/users).
3. Версия в начале пути. Всегда начинайте с версии: /v1/orders. Это позволяет менять структуру в будущем, не ломая старые клиенты.
4. Заглавные буквы только для аббревиатур. В остальном используйте нижний регистр (snake_case или kebab-case). Например, /product-categories лучше, чем /ProductCategories.

HTTP-методы как замена глаголам

Самое сложное для многих бэкендеров - перестать думать «что сделать» и начать думать «что изменить». Вот базовое соответствие между действиями и методами:

Обратите внимание на разницу между PUT и PATCH. PUT идемпотентен: если вы отправите один и тот же запрос дважды, результат будет тем же самым. PATCH часто используется для точечных правок, например, изменения только статуса заказа. Если вы используете PUT для частичного обновления, клиент должен передавать все поля, иначе недостающие могут обнулиться.

Работа со связями и вложенными ресурсами

Часто возникает вопрос: как спроектировать связь «один ко многим»? Например, у компании много сотрудников. Есть два популярных подхода.

Первый вариант: глубокая вложенность. Путь выглядит так: /companies/{companyId}/employees. Это интуитивно понятно и хорошо работает, когда сотрудники имеют смысл только в контексте конкретной компании. Но если сотрудник может работать в двух местах или вы хотите получить список всех сотрудников системы, этот путь становится неудобным.

Второй вариант: плоская структура с фильтрами. Вы создаете отдельный ресурс /employees и добавляете параметр фильтрации: /employees?company_id=15. Этот подход более гибкий и масштабируемый. Он позволяет легко строить сложные запросы, такие как «все сотрудники, чья зарплата выше X и которые работают в компании Y».

Для большинства современных микросервисных архитектур второй вариант предпочтительнее. Он сохраняет независимость ресурсов и упрощает кэширование на уровне CDN или прокси-серверов.

Типичные ошибки и как их избежать

Даже опытные команды иногда допускают ошибки, которые портят эстетику и функциональность API. Вот три самых частых:

• Использование ID в корне без контекста. Путь /items/5 ничего не говорит о том, что это за предмет. Лучше /products/5.
• Смешение сингулярной и плюральной форм. Если у вас есть /users, то получение одного пользователя должно быть /users/1, а не /user/1. Непоследовательность заставляет клиентов гадать.
• Игнорирование кодирования параметров. Если в названии товара есть пробелы или кириллица, обязательно используйте URL-encoding. /search?q=iphone%20case вместо /search?q=iphone case.

Также важно правильно обрабатывать ошибки. Вместо возврата пустого массива при отсутствии ресурса, возвращайте стандартный код состояния 404 Not Found. Это помогает клиентам быстро понять причину сбоя.

Практический пример: рефакторинг старого API

Допустим, у вас есть легаси-система с такими эндпоинтами:

• POST /api/addUser
• GET /api/getUserProfile?id=5
• POST /api/changePassword

Как перевести это в ресурсную модель?

1. POST /api/addUser становится POST /v1/users. Данные пользователя передаются в теле запроса.
2. GET /api/getUserProfile?id=5 становится GET /v1/users/5. ID теперь часть пути, а не query-параметра.
3. POST /api/changePassword - самый интересный случай. Пароль - это атрибут пользователя. Логичное решение: PATCH /v1/users/5/password. Мы создаем под-ресурс «password» внутри пользователя, чтобы явно указать, что меняем именно его, а не весь профиль.

Такой рефакторинг делает API предсказуемым. Любой разработчик, посмотрев на URL, сразу понимает, какая операция выполняется и над каким объектом.

Инструменты для проверки и документирования

Проектировать API на бумаге - одно, а проверить его работоспособность - другое. Для визуализации структуры и автоматической генерации документации используют спецификации. Самая популярная из них - OpenAPI (ранее Swagger). Она позволяет описать каждый эндпоинт, типы данных и возможные ошибки. Инструменты вроде Postman или Insomnia позволяют тестировать эти эндпоинты прямо из браузера, экономя время на написании скриптов для проверки.