Из чего состоит структура REST-запроса?

Структура REST-запроса

REST (Representational State Transfer) — архитектурный стиль, основанный на HTTP. Любой REST-запрос имеет четкую структуру, которая определяет, какое действие выполнить с ресурсом. Понимание этой структуры критично для проектирования API.

1. Метод HTTP (HTTP Method)

Определяет тип операции, которую необходимо выполнить:

• GET — получение данных ресурса, не изменяет состояние
• POST — создание нового ресурса
• PUT — полное обновление существующего ресурса
• PATCH — частичное обновление ресурса
• DELETE — удаление ресурса
• HEAD — получение заголовков без тела ответа
• OPTIONS — получение информации о доступных методах

Идемпотентность: GET, PUT, DELETE, HEAD, OPTIONS — идемпотентны (повторное выполнение не меняет результат). POST и PATCH — не идемпотентны.

2. URL (Uniform Resource Locator)

Определяет адрес ресурса. Структура:

https://api.example.com/api/v1/users/123

Компоненты:

• Схема — https:// (всегда HTTPS для API)
• Хост — api.example.com
• Путь (Path) — /api/v1/users/123 — идентифицирует ресурс
• Версия API — /v1/ — обеспечивает обратную совместимость
• ID ресурса — 123 — конкретный ресурс

Best Practice: использовать существительные во множественном числе (/users, /products), не глаголы (/getUsers — неправильно).

3. Query Parameters (Параметры запроса)

Передаются в строке запроса после ?. Используются для фильтрации, сортировки, пагинации:

GET /api/v1/users?limit=10&offset=0&sort=name&filter=active

Примеры:

• limit, offset — пагинация
• sort, order — сортировка
• filter, search — фильтрация
• include — какие поля включить

4. Заголовки (Headers)

Метаданные о запросе, передаются в виде ключ-значение:

Content-Type: application/json
Authorization: Bearer token123
Accept: application/json
User-Agent: MyApp/1.0
X-Request-ID: abc-123-def

Важные заголовки:

• Content-Type — формат тела запроса (application/json, application/x-www-form-urlencoded)
• Authorization — учетные данные (Bearer token, Basic auth)
• Accept — ожидаемый формат ответа
• User-Agent — информация о клиенте
• Custom Headers — X-* для пользовательских данных (ID сессии, версия API)

5. Тело запроса (Request Body)

Данные, отправляемые на сервер. Используется для POST, PUT, PATCH запросов. Обычно в формате JSON:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Форматы:

• JSON — стандарт в современных API
• XML — реже, для legacy систем
• Form Data — для HTML форм
• Binary — для файлов

Пример полного REST-запроса

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer token123
Content-Length: 47

{
  "name": "Alice",
  "email": "alice@example.com"
}

Типичный ответ (Response)

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 89

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2025-03-28T10:30:00Z"
}

Статус коды:

• 2xx — успех (200 OK, 201 Created, 204 No Content)
• 4xx — ошибка клиента (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx — ошибка сервера (500 Internal Server Error, 503 Service Unavailable)

Практические рекомендации

При проектировании REST API я придерживаюсь принципов:

• Версионирование API для поддержки старых клиентов
• Правильный выбор статус кодов для разных сценариев
• Документирование всех параметров и возможных ошибок
• Использование HTTPS для безопасности
• Rate limiting для защиты от abuse
• Логирование всех запросов для отладки и аналитики