Как передавать параметры в REST API?

Способы передачи параметров в REST API

В REST API существуют четыре основных способа передачи параметров, каждый из которых используется для разных целей и сценариев:

1. Path Parameters (Параметры пути)

Передаются непосредственно в URL-пути и идентифицируют конкретный ресурс:

GET /api/v1/users/123
GET /api/v1/posts/abc/comments/456

Когда использовать:

• Идентификация уникального ресурса
• Иерархические отношения между ресурсами
• Обязательные параметры

Преимущества: четкая структура URL, кэшируемость, безопасность

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

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

GET /api/v1/users?status=active&role=admin&page=2&limit=10
GET /api/v1/products?sort=price&filter=discount

Когда использовать:

• Фильтрация результатов
• Сортировка данных
• Пагинация
• Поиск
• Опциональные параметры

Преимущества: просто реализуются, удобны для фильтрации, видны в истории браузера

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

Передаются в теле HTTP-запроса, как правило, в JSON-формате:

POST /api/v1/users
Content-Type: application/json

{
  "name": "Иван",
  "email": "ivan@example.com",
  "age": 30,
  "address": {
    "city": "Москва",
    "street": "Арбат"
  }
}

Когда использовать:

• Создание новых ресурсов (POST)
• Обновление ресурсов (PUT/PATCH)
• Комплексные структуры данных
• Конфиденциальная информация
• Большие объемы данных

Преимущества: поддержка сложных структур, безопасность, нет ограничений по размеру

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

Передаются в заголовках HTTP-запроса для метаинформации:

GET /api/v1/users/123
Authorization: Bearer eyJhbGci...
X-API-Key: secret-key-123
X-Client-Version: 2.1
Accept-Language: ru-RU

Когда использовать:

• Аутентификация и авторизация
• Версионирование API
• Предпочтения клиента
• Пользовательские параметры
• Метаинформация

Преимущества: не видны в URL, стандартизированы, используются для управления запросом

Best Practices при передаче параметров

Консистентность: выбери один стиль именования и придерживайся его (snake_case или camelCase)

Валидация: всегда валидируй параметры на сервере, не доверяй клиенту

Документация: четко документируй все параметры, их типы и ограничения

Безопасность: передавай конфиденциальные данные в теле запроса или заголовках, никогда в URL

Версионирование: используй версии API в URL (/api/v1/) для обратной совместимости

Пагинация: всегда реализуй пагинацию для больших наборов данных

Обработка ошибок: верни понятные коды ошибок и сообщения при неправильных параметрах

Примеры комбинирования способов

На практике часто комбинируют несколько способов:

GET /api/v1/users/123/posts?status=published&sort=date&limit=10
Authorization: Bearer token
X-Request-ID: uuid

Это обеспечивает ясную, безопасную и гибкую передачу данных.