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

Question

deepseek-v3.2 · Accepted Answer

## Основные правила и соглашения REST API

REST (Representational State Transfer) — это архитектурный стиль, а не стандарт, поэтому строгих правил нет, но существуют общепринятые **соглашения и best practices**, которые делают API интуитивно понятными, последовательными и удобными в использовании.

### 1. Использование существительных во множественном числе для ресурсов

Ресурсы (сущности) должны обозначаться существительными, а не глаголами. Предпочтительно использовать множественное число для единообразия.

```http
# Правильно
GET /api/users
GET /api/products
POST /api/orders

# Неправильно
GET /api/getUsers
GET /api/product
POST /api/createOrder
```

### 2. Иерархическая структура для связей между ресурсами

Для отражения отношений "принадлежности" или иерархии используются вложенные пути.

```http
# Получить все заказы пользователя с ID=5
GET /api/users/5/orders

# Получить конкретный заказ №12 пользователя с ID=5
GET /api/users/5/orders/12
```

Однако для плоских структур или чтобы избежать глубокой вложенности, часто используют query-параметры:
```http
GET /api/orders?userId=5
```

### 3. Использование HTTP-методов (глаголов) для операций

CRUD-операции должны соответствовать HTTP-методам, а не быть частью URL.

| Метод   | Операция | Пример |
|---------|----------|---------|
| **GET**    | Получение ресурса(ов) | `GET /api/users` |
| **POST**   | Создание нового ресурса | `POST /api/users` |
| **PUT**    | Полное обновление ресурса | `PUT /api/users/5` |
| **PATCH**  | Частичное обновление ресурса | `PATCH /api/users/5` |
| **DELETE** | Удаление ресурса | `DELETE /api/users/5` |

### 4. Использование kebab-case или snake_case в URL

В URL рекомендуется использовать строчные буквы и разделять слова дефисами (`kebab-case`) или подчеркиваниями (`snake_case`). **CamelCase** в URL нежелателен, так как некоторые серверы чувствительны к регистру.

```http
# Правильно (kebab-case)
GET /api/user-profiles

# Правильно (snake_case)
GET /api/user_profiles

# Не рекомендуется (CamelCase)
GET /api/userProfiles
```

### 5. Фильтрация, сортировка, пагинация через query-параметры

Эти операции не являются частью пути к ресурсу и выносятся в параметры запроса.

```http
# Фильтрация и поиск
GET /api/products?category=electronics&minPrice=100

# Сортировка
GET /api/products?sort=-price,createdAt  # `-` означает DESC

# Пагинация
GET /api/products?page=2&limit=20

# Выбор полей (Field Selection)
GET /api/users?fields=id,name,email
```

### 6. Использование статус-кодов HTTP

Ответы сервера должны содержать семантически правильные HTTP-статусы:
*   **2xx** — Успех (200 OK, 201 Created, 204 No Content)
*   **3xx** — Перенаправление
*   **4xx** — Ошибка клиента (400 Bad Request, 404 Not Found, 409 Conflict)
*   **5xx** — Ошибка сервера (500 Internal Server Error)

### 7. Версионирование API

Версию API следует включать в URL (рекомендуется) или в заголовки запроса (например, `Accept`). Это позволяет вносить breaking changes, не ломая старых клиентов.

```http
# Версионирование в URL (наиболее распространенный подход)
GET /api/v1/users
GET /api/v2/users

# Через заголовок Accept
GET /api/users
Headers: Accept: application/vnd.company.app-v1+json
```

### 8. Именование вложенных ресурсов (коллекций)

Для операций над всей коллекцией вложенного ресурса используется путь, а для операций над конкретным элементом — его идентификатор.

```http
# Коллекция подзадач задачи №10
GET    /api/tasks/10/subtasks   # Получить все
POST   /api/tasks/10/subtasks   # Создать новую

# Конкретная подзадача №5 задачи №10
GET    /api/tasks/10/subtasks/5
PUT    /api/tasks/10/subtasks/5
DELETE /api/tasks/10/subtasks/5
```

### 9. Использование **HATEOAS** (Hypermedia as the Engine of Application State)

Продвинутый принцип REST, при котором ответы API содержат гиперссылки на доступные действия, что делает API самоописываемым.

```json
{
  "id": 123,
  "name": "John Doe",
  "links": [
    { "rel": "self", "href": "/api/users/123" },
    { "rel": "orders", "href": "/api/users/123/orders" }
  ]
}
```

### 10. Именование для не-CRUD операций

Иногда ресурсу требуется действие, которое не укладывается в стандартные CRUD-операции. В таких случаях используют:
*   **Дополнительный путь (суррогатный ресурс):**
    ```http
    POST /api/users/5/activate
    POST /api/emails/42/send
    ```
*   **Query-параметр с PUT/PATCH:**
    ```http
    PATCH /api/users/5?action=activate
    ```

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

Главная цель этих правил — **создание предсказуемого, понятного и единообразного API**. Разработчик, знакомый с REST, должен интуитивно понимать, как работать с вашим API, даже без глубокого изучения документации. Соблюдение этих соглашений упрощает интеграцию, уменьшает количество ошибок и улучшает опыт разработчиков, которые будут потреблять ваш API. Всегда стоит документировать отклонения от общепринятых практик, если они обоснованы спецификой домена.

Метод	Операция	Пример
GET	Получение ресурса(ов)	`GET /api/users`
POST	Создание нового ресурса	`POST /api/users`
PUT	Полное обновление ресурса	`PUT /api/users/5`
PATCH	Частичное обновление ресурса	`PATCH /api/users/5`
DELETE	Удаление ресурса	`DELETE /api/users/5`

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

Комментарии (1)

Основные правила и соглашения REST API

1. Использование существительных во множественном числе для ресурсов

2. Иерархическая структура для связей между ресурсами

3. Использование HTTP-методов (глаголов) для операций

4. Использование kebab-case или snake_case в URL

5. Фильтрация, сортировка, пагинация через query-параметры

6. Использование статус-кодов HTTP

7. Версионирование API

8. Именование вложенных ресурсов (коллекций)

9. Использование HATEOAS (Hypermedia as the Engine of Application State)

10. Именование для не-CRUD операций

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