REST API

URL структура REST API: Правильное построение URL

📚 26 вопросовПройти тест →
Лекция

URL структура REST API: Правильное построение URL

REST API

URL структура REST API: Правильное построение URL

Введение: адрес дома 🏠

URL в API — это адрес, по которому «живёт» ресурс.
Если адреса хаотичные, клиент теряется так же, как в городе без улиц и домов.
💡 Совет: хороший URL читается как предложение: «получи список курсов».
✅ Вывод: URL должен быть понятным, как обычный адрес.

Проблема → решение

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

Чем помогает и как работает

Правильная структура URL делает API читаемым и единообразным. Это снижает путаницу и упрощает поддержку документации.
Как это работает:
  1. URL описывает ресурс существительным (/courses).
  2. Конкретный объект задаём через id (/courses/10).
  3. Условия выдачи (фильтры, сортировка) помещаем в query.
✅ Вывод: ресурсные URL делают API понятным и стабильным.

Ключевые термины (простыми словами)

  • Resource (ресурс) — объект API (курс, студент).
  • Collection (коллекция) — список ресурсов (courses).
  • Path parameter — переменная в пути (/courses/{id}).
  • Query parameter — параметры после ? (фильтры, сортировка).
  • Nested resource — вложенный ресурс (/courses/{id}/lessons).
  • HATEOAS — ответы содержат ссылки на следующие действия/ресурсы, чтобы клиент мог «следовать» по API.
✅ Вывод: термины помогают строить URL «по полочкам».

Самое важное (must‑know)

  • URL = ресурс, не действие (без глаголов).
  • Коллекции — во множественном числе (/courses).
  • ID в пути, фильтры — в query.
  • Глубокая вложенность — максимум 1–2 уровня.
  • Один стиль для всех URL.
✅ Вывод: эти правила делают API читаемым и масштабируемым.

1. Ресурсные URL (существительные)

Назначение: описывать, что это за объект.
Простыми словами: URL говорит «что это», а не «что сделать».
Аналогия: на двери пишут «кабинет 204», а не «работать».
Пример:
/courses/students
🔎 Как это происходит на практике:
  1. Клиент запрашивает список по GET /courses.
  2. URL описывает ресурс, а не действие.
  3. Сервер возвращает коллекцию курсов.
Характеристики:
  • ✅ существительные;
  • ✅ читается как объект;
  • ✅ без глаголов.
Когда использовать: всегда для ресурсов.
✅ Вывод: URL = имя ресурса.

2. Коллекция и конкретный объект

Назначение: различать список и один элемент.
Простыми словами: один URL — список, другой — конкретный объект.
Аналогия: «улица» vs «дом №10».
Пример:
/courses/courses/10
🔎 Как это происходит на практике:
  1. Клиент открывает /courses и получает список.
  2. Затем запрашивает /courses/10 для деталей.
  3. Один шаблон работает для всех ресурсов.
Характеристики:
  • ✅ коллекция — без id;
  • ✅ объект — с id;
  • ✅ единый паттерн.
Когда использовать: когда есть список и детали.
✅ Вывод: коллекция и объект — два разных адреса.

3. Вложенность и иерархия

Назначение: показать связь между ресурсами.
Простыми словами: вложенный URL = «часть целого».
Аналогия: комната внутри здания.
Пример:
/courses/10/lessons
🔎 Как это происходит на практике:
  1. Клиенту нужны уроки курса 10.
  2. Он использует /courses/10/lessons.
  3. Сервер возвращает дочерние ресурсы.
Характеристики:
  • ✅ подходит для «дочерних» сущностей;
  • ✅ не углубляемся больше 2 уровней.
Когда использовать: когда ресурс принадлежит другому.
✅ Вывод: вложенность = связь.

4. Query‑параметры — для фильтров

Назначение: задавать условия и сортировку.
Простыми словами: путь говорит «где», query — «какие».
Аналогия: адрес дома + «этаж, подъезд».
Пример:
/courses?level=beginner&sort=rating
🔎 Как это происходит на практике:
  1. Клиент передаёт /courses?level=beginner&sort=rating.
  2. Сервер применяет фильтр и сортировку.
  3. Ответ содержит отфильтрованный список.
Характеристики:
  • ✅ фильтры и сортировка;
  • ✅ опционально;
  • ✅ не для обязательных параметров.
Когда использовать: фильтры, пагинация.
✅ Вывод: условия — в query, не в пути.

5. Действия как под‑ресурсы

Назначение: описывать операции, которые не являются ресурсом.
Простыми словами: если это действие, добавляем под‑путь.
Аналогия: «запустить курс» как отдельный процесс.
Пример:
POST /courses/10/publish
🔎 Как это происходит на практике:
  1. Клиент отправляет POST /courses/10/publish.
  2. Сервер выполняет действие публикации.
  3. Возвращает результат операции и статус.
Характеристики:
  • ✅ действие — отдельный URL;
  • ✅ метод определяет тип операции.
Когда использовать: публикация, активация, отмена.
✅ Вывод: действия = под‑ресурсы.

6. Единый стиль и читаемость

Назначение: сделать URL визуально одинаковыми.
Простыми словами: все адреса выглядят как из одного шаблона.
Аналогия: единые дорожные знаки в городе.
Пример:
/kebab-case
🔎 Как это происходит на практике:
  1. Команда выбирает kebab‑case для всех URL.
  2. Все эндпоинты выглядят единообразно.
  3. Документация и клиенты не путаются.
Характеристики:
  • ✅ единый стиль (kebab‑case);
  • ✅ без расширений (.php);
  • ✅ без лишних слов.
Когда использовать: всегда.
✅ Вывод: единый стиль = меньше ошибок.

Сравнение: хороший vs плохой URL

ПлохоХорошоПочему
/getCourses/coursesглагол → ресурс
/course/10/courses/10коллекция во мн. числе
/courses/delete/10DELETE /courses/10действие = метод
/courses?filter=/courses?level=понятный фильтр
✅ Вывод: URL должен быть «читаемым адресом».

Часто спрашивают на собеседованиях

  • Почему нельзя глаголы в URL? действие — это метод.
  • Коллекция или объект? коллекция без id, объект с id.
  • Query или path? query для фильтров и сортировки.
  • Насколько глубоко вкладывать? 1–2 уровня максимум.
  • Нужно ли расширение (.php)? нет, API не про файлы.
✅ Вывод: эти вопросы — классика интервью.

Типичные ошибки

Ошибка 1: глаголы в URL

❌ /getCourses
✅ /courses
Почему: действие — это метод.
Практический пример: GET /courses.

Ошибка 2: глубокая вложенность

❌ /users/1/orders/3/items/5/products
✅ /orders/3/items
Почему: длинные URL сложно поддерживать.

Ошибка 3: фильтр в пути

❌ /courses/level/beginner
✅ /courses?level=beginner
Почему: фильтры — это query.

Ошибка 4: смешанный стиль

❌ /course_list и /courses-list
✅ единый kebab‑case
Почему: единый стиль проще читать.

Ошибка 5: действия в path без метода

❌ /courses/delete/10
✅ DELETE /courses/10
Почему: метод описывает действие.

Best Practices

  • Используйте существительные в URL.
  • Коллекции — во множественном числе.
  • ID только в path, фильтры — в query.
  • Действия оформляйте как под‑ресурс + POST.
  • Держите вложенность максимум 2 уровня.
  • Следуйте одному стилю (kebab‑case).

Заключение

🧭 URL — это карта вашего API.
🏠 Чем понятнее адреса, тем быстрее клиент ориентируется.
✅ Хорошая структура = меньше ошибок и вопросов.
Теперь вы умеете строить URL так, чтобы ими было удобно пользоваться каждый день.
🎯

Проверьте знания

Закрепите материал — пройдите тест по теме «URL структура REST API: Правильное построение URL»

Пройти тест →