Что такое контракт API и зачем он нужен?

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

Что включает контракт API:

• Базовый URL и эндпоинты (например, /api/v1/users).
• HTTP-методы (GET, POST, PUT, DELETE, PATCH) для каждого эндпоинта.
• Параметры запроса: path (/users/{id}), query (?sort=asc), header, body.
• Формат и схема данных для запроса и ответа (обычно JSON, описанный через JSON Schema).
• Коды состояния HTTP (200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error) и их смысл.
• Схемы ошибок — унифицированный формат сообщений об ошибках.
• Аутентификация и авторизация (например, заголовок Authorization: Bearer <token>).

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

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 42
                  name:
                    type: string
                    example: "John Doe"
        '404':
          description: User not found

Зачем нужен контракт API?

1. Единый источник истины: Разработчики фронтенда и бэкенда работают по одной спецификации.
2. Автоматизация тестирования: Контракт позволяет генерировать моки-серверы и автоматически проводить контрактное тестирование (например, с помощью Pact, Postman, Schemathesis).
3. Контроль изменений: Контракт помогает отслеживать breaking changes (критические изменения) в API, которые могут сломать клиентов.
4. Документация: Современные инструменты (Swagger UI, Redoc) автоматически генерируют интерактивную документацию из контракта.

Роль тестировщика: Проверять соответствие реального поведения API его контракту, используя инструменты для контрактного и интеграционного тестирования.