Какие вопросы задать разработчику по спецификации формата и поведения API

Что проверяют

Умеете ли вы найти в API места, где две стороны легко поймут контракт по-разному, и договориться о них до написания кода. Вопрос встречается и у разработчиков, и у тестировщиков. Следом нередко просят рассказать, как вы проверяете, что реализация соответствует спецификации.

Как отвечать

Сначала спросите, есть ли OpenAPI-спецификация и считается ли она источником правды, или документацию пишут после кода. Дальше вопросы, на которых чаще всего расходятся:

• поля и типы: snake_case или camelCase, чем отличается null от отсутствующего поля, в каком формате даты (ISO 8601 с часовым поясом или без), как передаются деньги. Сумма во float теряет копейки, её передают строкой или целым числом в минимальных единицах;
• перечисления: что клиенту делать, если придёт значение, которого нет в спецификации;
• ошибки: единый формат тела, например по RFC 9457 (Problem Details), какие коды на что, как отдаются ошибки валидации по полям. Скажем, FastAPI по умолчанию отвечает 422 в собственном формате;
• списки: пагинация по смещению или по курсору, предельный размер страницы, стабильна ли сортировка;
• изменение данных: семантика PATCH (как обнулить поле и как оставить его нетронутым), защита от одновременной правки через ETag и If-Match, ключ идемпотентности для POST;
• ограничения: лимиты запросов, размер тела, таймауты, реакция на неизвестные поля во входных данных;
• развитие: как версионируется API, какие изменения считаются обратно совместимыми, как объявляют устаревание.

Скажите, что делаете с ответами: генерируете модели Pydantic из спецификации через datamodel-code-generator, а соответствие реализации проверяете контрактными тестами, например через schemathesis, который строит запросы по OpenAPI.

Где спотыкаются

Ограничиваются вопросами «формат JSON?» и «какая авторизация?». Проблемы на интеграции возникают в деталях: null, часовые пояса, пустой список против отсутствующего поля.

Не спрашивают о поведении при ошибках и повторах. В итоге клиент повторяет неидемпотентный запрос и создаёт дубли.

Принимают спецификацию на слово и не проверяют, что сервис ей действительно соответствует.