Какие правила именования в REST API ты знаешь?

Следование общепринятым правилам именования делает REST API интуитивно понятным и предсказуемым для потребителей.

Ключевые принципы:

1. Ресурсы — существительные, а не глаголы.

   • Хорошо: /users, /orders
   • Плохо: /getUsers, /createOrder
   • Почему: Глаголы уже заложены в HTTP-методах (GET, POST и т.д.).

2. Используйте множественное число для коллекций.

   • Хорошо: /products
   • Плохо: /product (если это коллекция)
   • Почему: Указывает, что эндпоинт возвращает список ресурсов.

3. Выражайте иерархию через слэш (/).

   • Пример: /users/{userId}/orders — получить заказы конкретного пользователя.
   • Почему: Четко показывает отношение «ресурс в ресурсе».

4. Используйте query-параметры для фильтрации, сортировки и пагинации.

   • Пример: GET /products?category=electronics&sort=price&page=2&limit=20
   • Почему: Параметры запроса не являются частью пути к ресурсу и предназначены для его модификации.

5. Используйте kebab-case (через дефис) в URL.

   • Хорошо: /user-roles
   • Плохо: /userRoles (camelCase) или /user_roles (snake_case)
   • Почему: Дефисы улучшают читаемость в браузерах и соответствуют стилю, принятому для доменов.

6. Действия определяются 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-метод для операции получения.