Контракт
и проверка соответствия

§1Что сервер обещает клиенту

Слово «контракт» в разработке означает не юридический документ, а набор обещаний, которые одна программа даёт другой. Разберём их на учебном сервисе. Service Desk API — сервис регистрации обращений в поддержку: сотрудник сообщает «не работает VPN», специалист меняет статус обращения, пока проблема не решена.

Обещания этого сервиса можно выписать по пунктам, и каждое из них проверяемо:

• по адресу /api/v1/tickets методом GET вернётся страница обращений;
• в каждом обращении будут поля id, title, description, status, created_at, updated_at;
• status примет одно из трёх значений: open, in_progress, closed;
• создание выполняется методом POST на тот же адрес и отвечает кодом 201, а адрес нового обращения приходит в заголовке Location;
• если обращения с таким идентификатором нет, придёт код 404 и тело в формате application/problem+json;
• операции записи требуют токен; без него — 401, с токеном только для чтения — 403.

Пока сервис выполняет эти обещания, любая программа, написанная по ним, работает. Если сервис меняет хотя бы одно обещание без предупреждения, перестаёт работать программа клиента, а не сам сервис. Автор изменения об этой программе может не знать и доступа к ней не имеет.

У контракта две стороны и один посредник — протокол HTTP. Клиент не видит ни языка сервера, ни его базы данных, ни числа запущенных экземпляров. Он видит адреса, методы, коды и JSON. Стандартизируют именно этот видимый слой: он сохраняется при переписывании сервера на другой язык и при смене базы данных.

§2Почему «работает» ещё не значит «готово»

Возьмём изменение, которое выглядит безобидно. Разработчик решил, что имя поля updated_at неудачное, и переименовал его в modified_at. Переименование он выполнил аккуратно: поправил схему ответа, хранилище и все тесты.

class Ticket(BaseModel):
    id: UUID
    title: str
    status: TicketStatus
    created_at: datetime
    updated_at: datetime

class Ticket(BaseModel):
    id: UUID
    title: str
    status: TicketStatus
    created_at: datetime
    modified_at: datetime

Запускаем проверки проекта. Все 31 тест проходят: сервис отвечает 200, отдаёт обращения, ошибки возвращает в прежнем формате. Со стороны кода изменение выполнено правильно.

...............................                                          [100%]
31 passed in 0.08s

Теперь посмотрим на то же изменение со стороны контракта. Инструмент oasdiff сравнивает описание API до и после изменения и перечисляет то, что сломает существующих клиентов. Вот его настоящий вывод на этой ветке:

in API GET /api/v1/tickets removed the required property `items/items/updated_at`
    from the response with the `200` status
in API POST /api/v1/tickets removed the required property `updated_at`
    from the response with the `201` status
in API GET /api/v1/tickets/open removed the required property `items/items/updated_at`
    from the response with the `200` status
in API GET /api/v1/tickets/{ticket_id} removed the required property `updated_at`
    from the response with the `200` status
in API PATCH /api/v1/tickets/{ticket_id} removed the required property `updated_at`
    from the response with the `200` status

Пять операций перестали отдавать поле, которое обещали. Мобильное приложение, написанное полгода назад, ищет в ответе updated_at, не находит и показывает пустую дату. Сервер при этом «работает»: отвечает 200 и не пишет ни одной ошибки в лог.

Тесты проверяют, что сервис делает то, что задумал автор изменения. Контрактные проверки отвечают на другой вопрос: продолжает ли сервис делать то, что обещал раньше. Поэтому зелёные тесты не означают, что контракт не нарушен.

§3Что именно стандартизируют

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

Последняя строка таблицы относится не к самому API, а к порядку работы с правилами. Ей посвящены модули 6 и 7.

§4Стандартизация и проверка соответствия

Дисциплина называется «стандартизация, сертификация и техническое документоведение». Первые два слова обозначают разные действия, и различать их нужно с самого начала.

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

§5Почему у API нет сертификата

В технике сертификация — процедура, в которой независимая сторона подтверждает соответствие продукта требованиям стандарта и выдаёт документ. Так сертифицируют кабель, детское автокресло, медицинский прибор. Продукт испытывают в аккредитованной лаборатории, а сертификат можно предъявить покупателю.

Для обычного REST API такой процедуры не существует. Нет органа, который выдаст вашему сервису документ «API соответствует правилам», потому что нет единого обязательного стандарта, которому такой сервис должен соответствовать. Есть стандарты протокола (их издаёт IETF), есть формат описания (его развивает OpenAPI Initiative), есть правила отдельных компаний — и они друг другу не тождественны.

Отдельные области — исключение. Платёжные сервисы проходят аудит PCI DSS, медицинские системы — проверки по локальному законодательству, государственные сервисы — требования регуляторов. Но это сертификация организации и процессов, а не «правильности API» как таковой.

§6Чем проверяют в этой книге

Раз внешнего органа нет, проверку берёт на себя репозиторий. В учебном проекте каждое правило привязано к инструменту, который применяет его автоматически.

Первые четыре проверки выполняют программы, последнюю — человек на ревью. Автоматически проверяется не всё: понятно ли названо поле, уместен ли выбранный код ответа, не раскрывает ли сообщение об ошибке лишнего. Чем больше правил переведено в тесты и правила линтера, тем меньше таких вопросов остаётся человеку.