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

Контракт API — это формальное соглашение, которое точно определяет, как клиентское приложение (например, фронтенд или мобильное приложение) должно взаимодействовать с серверным API. QA-инженер использует этот контракт как источник истины для создания тестов.

Ключевые компоненты API-контракта:

1. Базовый URL и эндпоинты: Адреса для доступа к ресурсам (например, https://api.example.com/v1/users).
2. HTTP-методы: Действия, которые можно выполнить с ресурсом: GET (получить), POST (создать), PUT/PATCH (обновить), DELETE (удалить).
3. Параметры запроса:
   • Path parameters: Часть URL (/users/{userId}).
   • Query parameters: Параметры после ? в URL (?sort=asc&limit=10).
   • Заголовки (Headers): Мета-информация (Authorization, Content-Type).
4. Тело запроса (Request Body): Данные, отправляемые на сервер (обычно в формате JSON или XML), включая обязательные и опциональные поля, типы данных и ограничения (валидация).
5. Тело ответа (Response Body): Структура и формат данных, возвращаемых сервером.
6. Коды состояния HTTP (Status Codes): Стандартные ответы: 2xx (успех), 4xx (ошибка клиента, например, 400 Bad Request, 404 Not Found), 5xx (ошибка сервера).
7. Схемы данных (Data Schemas): Точное определение структуры объектов запроса и ответа (используется JSON Schema, OpenAPI Schema).
8. Аутентификация и авторизация: Описание метода доступа (API Key, OAuth 2.0, JWT).
9. Скоростные ограничения (Rate Limiting): Правила по количеству запросов в единицу времени.

Пример фрагмента контракта в формате OpenAPI (Swagger), на основе которого строятся тесты:

openapi: 3.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                  minLength: 2
      responses:
        '201': # Код состояния
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input data

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 42
        email:
          type: string
        name:
          type: string

Для QA этот контракт критически важен: он позволяет автоматически генерировать тесты на валидацию схемы (с помощью инструментов вроде Dredd или Schemathesis), проверять граничные значения и гарантировать, что любые изменения API на стороне сервера не сломают клиент, если контракт остается прежним (тестирование на совместимость).