Средний ~22 мин чтения

Ресурсы и URL-структура

Урок 2 из 5 в курсе Проектирование REST API

Ресурсы и URL-структура

хорошая URL-структура делает API интуитивным: ресурсы именуются существительными, иерархия отражает вложенность.

Почему это важно: Непоследовательные URL — первый признак плохо спроектированного API. Предсказуемая структура снижает когнитивную нагрузку на разработчиков, интегрирующих API.

Главная идея

URL идентифицирует ресурс, а не действие. Используйте существительные во множественном числе, отражайте иерархию через вложенность, избегайте глаголов в URL.

Как это выглядит на практике

  1. GET /articles — коллекция статей.
  2. GET /articles/42 — конкретная статья с id=42.
  3. GET /articles/42/comments — комментарии к статье 42.
  4. POST /articles/42/comments — создать комментарий к статье 42.

Что происходит под капотом

  • Коллекция (collection) vs. элемент (item): /resources — коллекция, /resources/:id — элемент.
  • Вложенность URL (nesting) отражает принадлежность: /users/:id/orders — заказы конкретного пользователя.
  • Слишком глубокая вложенность (>3 уровней) усложняет клиентский код — лучше денормализовать URL.
  • Query-параметры используются для фильтрации, сортировки и пагинации: /articles?status=published&sort=created_at.

Типичные ошибки и заблуждения

  • Ошибка: URL должен описывать действие (getUserById). REST URL идентифицирует ресурс, а не операцию.
  • Ошибка: единственное или множественное число — неважно. Множественное число (users, orders) является устоявшимся соглашением.
  • Ошибка: вложенность URL можно делать произвольной глубины. Более трёх уровней создаёт проблемы с поддержкой.
  • Ошибка: query-параметры и path-параметры взаимозаменяемы. Path-параметры идентифицируют ресурс, query — уточняют запрос.

Ключевые выводы

  • URL = ресурс (существительное), метод = действие (глагол).
  • Коллекция: /resources; элемент: /resources/:id.
  • Query-параметры — для фильтрации и сортировки, не для идентификации.
  • Максимальная вложенность — 2-3 уровня.

Термины урока

Collection: URL, представляющий группу ресурсов (/users).
Item: URL, представляющий конкретный ресурс (/users/42).
Path parameter: переменная часть URL (/users/:id).
Query parameter: параметр после ? для фильтрации и уточнения.

Связь с работой backend-разработчика

В Rails ресурсная маршрутизация (resources :articles) автоматически генерирует правильные REST URL. Понимание соглашений помогает отступать от них осознанно.

Мини-разбор реальной ситуации

Команда проектирует API для блога. Первый вариант: /getArticle, /createComment, /deleteUser — всё с GET. После рефакторинга: GET/POST /articles, GET/PATCH/DELETE /articles/:id, POST /articles/:id/comments. API стал предсказуемым без документации.

Что запомнить

  • Существительные в URL, глаголы — в HTTP-методе.
  • Множественное число для коллекций: /users, /orders.
  • Не углубляйте вложенность больше трёх уровней.

Итог

Правильная URL-структура — основа предсказуемого API. Следование соглашениям делает интеграцию интуитивной даже без документации.