Из чего состоит контракт API между сервером и клиентом

Состав контракта API между сервером и клиентом

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

1. Базовый URL (Endpoint Root)

Это основа всех запросов. Например, https://api.example.com/v1. Версия (v1) часто включается в URL для управления изменениями без нарушения работы существующих клиентов.

2. Конечные точки (Endpoints) и HTTP-методы

Каждая конечная точка соответствует конкретному ресурсу или действию и используется с определенным HTTP-методом.

GET    /api/v1/users       # Получить список пользователей
POST   /api/v1/users       # Создать нового пользователя
GET    /api/v1/users/{id}  # Получить пользователя по ID
PUT    /api/v1/users/{id}  # Полное обновление пользователя
PATCH  /api/v1/users/{id}  # Частичное обновление
DELETE /api/v1/users/{id}  # Удалить пользователя

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

• Path Parameters: Часть URL, идентифицирующая ресурс (например, {id}).
• Query Parameters: Параметры после ? для фильтрации, сортировки, пагинации (?page=2&limit=10).
• Request Headers: Мета-информация: тип контента (Content-Type: application/json), авторизация (Authorization: Bearer <token>).

4. Форматы данных (Request/Response Bodies)

Контракт строго определяет структуру и тип данных для тел запроса и ответа. Чаще всего используется JSON.

// Пример запроса на создание пользователя (Request Body)
{
  "name": "Иван Иванов",
  "email": "ivan@example.com",
  "age": 30
}

// Пример успешного ответа (Response Body)
{
  "id": 12345,
  "name": "Иван Иванов",
  "email": "ivan@example.com",
  "createdAt": "2023-10-01T12:00:00Z"
}

Для строгой валидации структур данных часто используются JSON Schema или OpenAPI/Swagger Specification.

5. Коды состояния HTTP (Status Codes)

Стандартизированные трехзначные числа, которые мгновенно сообщают клиенту результат операции.

• 2xx — Успех (200 OK, 201 Created).
• 3xx — Перенаправление.
• 4xx — Ошибка клиента (400 Bad Request, 401 Unauthorized, 404 Not Found).
• 5xx — Ошибка сервера (500 Internal Server Error).

6. Схемы аутентификации и авторизации

Контракт должен явно указывать, как клиент должен подтверждать свою подлинность. Распространенные методы:

• API Keys
• OAuth 2.0 / Bearer Tokens (JWT)
• Basic Authentication

7. Обработка ошибок (Error Handling)

Единообразный формат сообщений об ошибках — критически важная часть контракта. Он позволяет клиенту программно реагировать на сбои.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле 'email' является обязательным.",
    "details": [
      {"field": "email", "issue": "required"}
    ]
  }
}

8. Пагинация, сортировка, лимиты скорости (Rate Limiting)

• Пагинация: Описывает, как получать большие наборы данных по частям (например, через параметры offset/limit или cursor).
• Rate Limiting: Ограничение количества запросов за период времени. Контракт может определять заголовки для информирования клиента об лимитах (X-RateLimit-Limit, X-RateLimit-Remaining).

9. Формальная спецификация

На практике контракт часто документируется в виде машиночитаемой спецификации, которая служит единым источником истины. Самые популярные форматы:

• OpenAPI (Swagger): Де-факто стандарт для REST API.
• AsyncAPI: Для событийно-ориентированных и streaming API.
• GraphQL Schema: Для API GraphQL, который сам по себе является строгим контрактом.

Важность для QA Automation

Для инженера по автоматизации тестирования контракт API — это основной артефакт для:

• Создания точных и стабильных тестовых сценариев (настройка запросов, валидация ответов).
• Контрактного тестирования (Contract Testing) с использованием инструментов вроде Pact или Spring Cloud Contract, которое проверяет, что клиент и сервер соблюдают соглашение, не требуя развернутой среды.
• Валидации схемы ответов (соответствие JSON Schema).
• Тестирования негативных сценариев (ошибки 4xx/5xx, неверные типы данных).

Нарушение контракта (например, изменение формата ответа поля email с строки на объект без изменения версии API) приводит к поломке клиентских приложений. Поэтому ясный, детальный и стабильный контракт — это залог успешной и масштабируемой интеграции между системами.