Ответ
Следование общепринятым правилам именования делает REST API интуитивно понятным и предсказуемым для потребителей.
Ключевые принципы:
-
Ресурсы — существительные, а не глаголы.
- Хорошо:
/users,/orders - Плохо:
/getUsers,/createOrder - Почему: Глаголы уже заложены в HTTP-методах (GET, POST и т.д.).
- Хорошо:
-
Используйте множественное число для коллекций.
- Хорошо:
/products - Плохо:
/product(если это коллекция) - Почему: Указывает, что эндпоинт возвращает список ресурсов.
- Хорошо:
-
Выражайте иерархию через слэш (
/).- Пример:
/users/{userId}/orders— получить заказы конкретного пользователя. - Почему: Четко показывает отношение «ресурс в ресурсе».
- Пример:
-
Используйте query-параметры для фильтрации, сортировки и пагинации.
- Пример:
GET /products?category=electronics&sort=price&page=2&limit=20 - Почему: Параметры запроса не являются частью пути к ресурсу и предназначены для его модификации.
- Пример:
-
Используйте kebab-case (через дефис) в URL.
- Хорошо:
/user-roles - Плохо:
/userRoles(camelCase) или/user_roles(snake_case) - Почему: Дефисы улучшают читаемость в браузерах и соответствуют стилю, принятому для доменов.
- Хорошо:
-
Действия определяются HTTP-методами.
GET /users— получить список пользователей.POST /users— создать нового пользователя.PUT /users/{id}— полностью обновить пользователя.PATCH /users/{id}— частично обновить пользователя.DELETE /users/{id}— удалить пользователя.
Сравнение на практике:
# Несогласованный, не-RESTful подход
GET /getUserOrders?userId=123
# RESTful подход
GET /users/123/ordersВторой вариант явно указывает на ресурс «заказы», вложенный в ресурс «пользователь с id=123», и использует стандартный HTTP-метод для операции получения.
Ответ 18+ 🔞
А, ну вот, опять про эти ваши REST API правила начинают. Слушай, а ведь реально, если их не соблюдать, получается такая каша, что потом сам чёрт ногу сломит, пытаясь понять, что этот эндпоинт делает. Прям как в том анекдоте про Герасима — хотел сказать, а нихуя не может, только «Му-му».
Вот смотри, главная фишка — ресурсы это у тебя существительные, а не глаголы. Это как в магазин прийти и сказать: «Мне операция-получения-хлеба». Тебя там пошлют нахуй, и правильно сделают. Ты просто говоришь: «Хлеба». Так и тут.
- Нормально:
/users,/orders— вот они, предметы, с которыми работаем. - Полный пиздец:
/getUsers,/createOrder— это уже не ресурс, а инструкция. Глаголы-то куда девать? Они уже есть — это HTTP-методы!GET— получить,POST— создать. Зачем одно и то же два раза называть? Умножение сущностей, блядь.
И ещё, коллекции — это множественное число. GET /products. Это же логично, ёпта! Приходишь на склад — там продукты, а не один продукт валяется. Если скажешь /product, все подумают, что ты про один конкретный, а нихуя — там список. Запутаешь всех, включая себя через месяц.
Теперь про вложенность. Это как матрёшка, блядь. Хочешь заказы пользователя? Так и строй путь: /users/{userId}/orders. Прям видно, что заказы внутри пользователя. Чисто, понятно, в рот меня чих-пых. Не надо выдумывать /getUserOrders?userId=123. Это же пиздец какой-то, честное слово. Смотри, как красиво:
# Это говно какое-то, не делай так
GET /getUserOrders?userId=123
# А вот это — красота, RESTful как швейцарские часы
GET /users/123/ordersЧувствуешь разницу? Во втором случае даже обезьяна поймёт, что мы лезем к юзеру 123 и смотрим его ордера.
А если надо отсортировать, отфильтровать или страницу какую выбрать — это query-параметры. Не лепи всё в путь! Путь — это святое, это адрес ресурса. А всякие ?category=electronics&sort=price — это уже уточнения, как тебе этот ресурс подать. Разделяй, блядь, мух и котлеты.
И да, чуть не забыл — в URL используй kebab-case, через дефис. user-roles, client-profiles. Не userRoles (это camelCase, он для кода) и не user_roles (это snake_case, он для баз). В URL дефисы читабельнее, и браузеры их любят. Не усложняй, ёбаный насос.
Короче, вся суть в том, чтобы API был предсказуемым. Как хороший друг — не подставляет, не меняет правила игры. Захотел создать юзера — POST на /users. Удалить — DELETE на /users/456. Всё. Никакой магии. А то начнёшь выдумывать /doActionWithUser, и потом сам будешь ебаться, вспоминая, как это работает. Доверия к такому API — ноль ебать. Делай по уму, не будь распиздяем.
