REST API naming best practices

REST API Naming Best Practices

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

REST API Naming Best Practices

REST API naming best practices

REST API Naming Best Practices

Введение: таблички на дверях 🏷️

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

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

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

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

Нейминг помогает быстро понять, что делает эндпоинт, ещё до чтения документации. Он снижает риск ошибок и ускоряет работу команды.
Как это работает:
  1. Мы выбираем один стиль и набор правил.
  2. Любой разработчик может «угадать» адрес по названию ресурса.
  3. Клиенты получают предсказуемые URL.
✅ Вывод: хороший нейминг делает API удобным и стабильным.

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

  • Resource (ресурс) — сущность, например «курс».
  • Endpoint (эндпоинт) — адрес ресурса в API.
  • Collection (коллекция) — список ресурсов (/courses).
  • Path parameter (параметр пути) — ID в адресе (/courses/10).
  • Query parameter (параметр запроса) — условия поиска (?level=beginner).
  • kebab-case (кебаб‑кейс) — слова через дефис: user-profiles.
  • snake_case (снэйк‑кейс) — слова через подчёркивание: user_profiles.

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

  • URL описывает ресурс, а действие задаёт HTTP‑метод.
  • Коллекции пишем во множественном числе.
  • ID всегда в пути, фильтры и сортировка — в query.
  • Выбираем один стиль (kebab‑case или snake_case) и держим его везде.
  • Избегаем глаголов и лишних слов в URL.
✅ Вывод: если эти правила соблюдены, API читается «с ходу».

1. Ресурсные названия — только сущности

Назначение: показать, какой объект доступен по адресу. Простыми словами: в URL пишем «что это», а не «что сделать». Аналогия: на двери пишут «Кабинет», а не «Зайди».
Пример:
GET /coursesPOST /courses# плохо: /getCourses, /createCourse
🔎 Как это происходит на практике:
  1. Клиент вызывает GET /courses.
  2. Сервер понимает, что нужен список курсов.
  3. Возвращает коллекцию ресурсов.
Характеристики:
  • ✅ В URL только существительные.
  • ✅ Действие видно из HTTP‑метода.
  • ✅ Названия читаются без подсказок.
Когда использовать: всегда, когда описываешь ресурсы API. ✅ Вывод: ресурсные имена делают API понятным.

2. Коллекции во множественном числе

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

3. Единый стиль: kebab‑case или snake_case

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

4. ID в пути, условия в query

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

5. Действия — через под‑ресурсы и методы

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

6. Короткие и читаемые URL

Назначение: уменьшить шум и ошибки. Простыми словами: чем короче адрес, тем проще его понять. Аналогия: короткий адрес быстрее запомнить.
Пример:
GET /courses/10/lessons# плохо: /courses/10/all-lessons-for-course
🔎 Как это происходит на практике:
  1. Команда убирает лишние слова.
  2. Оставляет только смысловые части.
  3. URL становится короче и яснее.
Характеристики:
  • ✅ Нет расширений вроде .php.
  • ✅ Нет «лишних» слов.
  • ✅ Вложенность не глубже 1–2 уровней.
Когда использовать: всегда, особенно в публичных API. ✅ Вывод: короткие URL легче читать и поддерживать.

Сравнение хорошего и плохого нейминга

ХорошоПлохоПочему
/courses/getCoursesдействие должно быть в методе
/courses/10/course?id=10ID должен быть в пути
/courses?level=beginner/courses/level/beginnerфильтр — это query
/user-profiles/userProfilesодин стиль на весь API

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

  • Почему в REST не используют глаголы в URL и где тогда «действие».
  • Чем path‑параметры отличаются от query‑параметров.
  • Зачем нужен единый стиль (kebab/snake) и что будет, если смешивать.
  • Когда допустима вложенность и почему её ограничивают 1–2 уровнями.
  • Как правильно оформлять нестандартные действия (publish, archive).
✅ Вывод: эти вопросы проверяют понимание, а не знание терминов.

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

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

❌ Неправильно: /getCourses
✅ Правильно: /courses
Почему: действие определяется HTTP‑методом.

Ошибка 2: Смешение стилей

❌ Неправильно: /userProfiles рядом с /user_profiles
✅ Правильно: выбрать один стиль и держать его
Почему: смешение ломает предсказуемость.

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

❌ Неправильно: /courses/level/beginner
✅ Правильно: /courses?level=beginner
Почему: фильтры — это условия, а не адрес ресурса.

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

❌ Неправильно: /users/1/courses/2/lessons/3/tasks/4
✅ Правильно: остановиться на 1–2 уровнях
Почему: слишком глубокие URL трудно читать.

Ошибка 5: Лишние слова

❌ Неправильно: /courses/all-available-courses
✅ Правильно: /courses
Почему: адрес должен быть коротким.

Ошибка 6: Расширения файлов

❌ Неправильно: /courses.php
✅ Правильно: /courses
Почему: API — это ресурсы, не файлы.

Best Practices

  • Используй существительные и множественное число.
  • Держи единый стиль именования во всех URL.
  • Разделяй ID (path) и условия (query).
  • Действия оформляй через методы или под‑ресурсы.
  • Ограничивай вложенность 1–2 уровнями.
  • Убирай лишние слова и расширения.

Заключение

Хороший нейминг — это навигация по API. Он помогает быстрее понимать эндпоинты и снижает ошибки. Если правила простые и единые — API становится дружелюбным.
✅ Вывод: нейминг — это часть качества API, а не косметика.
🎯

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

Закрепите материал — пройдите тест по теме «REST API Naming Best Practices»

Пройти тест →