Из чего состоит API запрос

Из чего состоит API запрос

API запрос — это структурированное сообщение, которое клиент (например, веб-браузер, мобильное приложение или другой сервер) отправляет серверу для выполнения определённой операции. Как специалист с более чем 10-летним опытом в автоматизации тестирования, я рассматриваю API запрос как фундаментальный строительный блок интеграционного взаимодействия между системами. Его корректное формирование и понимание структуры критичны для создания надёжных автоматизированных тестов, отладки и анализа логов.

Основные компоненты API запроса можно разделить на несколько ключевых частей:

1. Метод запроса (HTTP Method)

Это глагол, определяющий тип операции, которую нужно выполнить с ресурсом. Наиболее распространённые методы:

• GET: Получение данных с сервера. Идемпотентный и безопасный (не должен изменять состояние сервера).
• POST: Создание нового ресурса или отправка данных для обработки.
• PUT: Полное обновление существующего ресурса (замена).
• PATCH: Частичное обновление ресурса.
• DELETE: Удаление ресурса.
• HEAD, OPTIONS – используются для получения метаинформации.

2. URL (Uniform Resource Locator) или Endpoint

Адрес, по которому располагается ресурс или выполняемая операция на сервере. Состоит из:

• Протокол (чаще https://)
• Доменное имя или IP-адрес сервера (api.example.com)
• Порт (обычно неявный: 443 для HTTPS, 80 для HTTP)
• Путь к ресурсу (/users/123/orders)
• Query Parameters (Параметры строки запроса): Необязательные параметры, добавляемые после ? в формате key=value, разделённые & (например, ?limit=10&offset=0&sort=date). Используются для фильтрации, пагинации, сортировки.

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

Набор пар ключ: значение, которые передают метаинформацию о запросе. Это критически важная часть для безопасности, кеширования, определения формата данных.

• Заголовки общего назначения: Host, User-Agent, Connection.
• Заголовки запроса: Authorization (токены Bearer, Basic Auth), Content-Type (например, application/json, application/xml), Accept (указывает, какой формат данных клиент готов принять в ответ).
• Пользовательские заголовки (Custom Headers): Часто начинаются с X-, например, X-API-Key, X-Request-ID.

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

Необязательный компонент, присутствующий в основном в запросах POST, PUT, PATCH. Содержит данные, которые клиент отправляет на сервер. Формат определяется заголовком Content-Type.

• JSON (наиболее распространён в REST API):

  {
    "username": "john_doe",
    "email": "john@example.com",
    "active": true
  }
  

• XML:

  <user>
      <username>john_doe</username>
      <email>john@example.com</email>
      <active>true</active>
  </user>
  

• Form Data (application/x-www-form-urlencoded или multipart/form-data для загрузки файлов): Параметры в виде key=value.

5. Прочие компоненты (зависят от типа API)

• Path Parameters (Параметры пути): Переменные части URL, выделенные фигурными скобками (например, /users/{userId}). В запросе заменяются на фактические значения (/users/123).
• Cookies: Могут автоматически отправляться браузером для поддержания сессии.
• Параметры аутентификации: Могут быть частью URL (устаревший и небезопасный способ), заголовков или тела.

Пример полного запроса (в контексте автоматизации на Python с requests)

import requests

# 1. Метод: POST
# 2. URL с endpoint
url = "https://api.example.com/v1/users"

# 3. Заголовки
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ...",
    "X-Correlation-ID": "test-run-789"
}

# 4. Тело запроса (JSON)
payload = {
    "name": "Alice Smith",
    "email": "alice@example.com",
    "age": 30
}

# 5. Параметры строки запроса (можно передать отдельно словарем `params`)
# В данном примере они не используются.

# Формирование и отправка запроса
response = requests.post(url=url, json=payload, headers=headers)

print(f"Status Code: {response.status_code}")
print(f"Response Body: {response.json()}")

В автоматизированном тестировании мы должны валидировать все эти компоненты как в запросе, так и в ответе. Мы проверяем:

• Корректность HTTP-кода ответа.
• Соответствие структуры и значений тела ответа контракту (схеме, например, JSON Schema).
• Наличие и корректность нужных заголовков в ответе.
• Соответствие бизнес-логике (например, созданный через POST ресурс корректно возвращается GET-запросом).

Понимание состава API запроса — это первый шаг к написанию эффективных, стабильных и поддерживаемых автотестов для API, позволяющий точно локализовать проблемы: неверный endpoint, отсутствие заголовка авторизации, некорректный формат тела или ошибка в параметрах запроса.