В какой-то момент я понял, что про партнёрства и интеграции мы слишком часто говорим абстрактно — на уровне «API есть, документация есть, поехали». А вот про реальное качество этих API и про то, как с ними живётся, говорим куда реже.

Вспомнилась история из практики. Работали мы с одним итальянским провайдером квалифицированной электронной подписи. По европейским меркам — вполне себе серьёзный игрок, что-то вроде местного аналога Контура. И здесь сразу важный нюанс: в Европе электронная подпись используется не только для фиксации неизменности документа и авторства подписанта, но и как инструмент KYC. То есть это уже не совсем «каноничный» кейс подписи, а такой сайд-кейс. Формально подпись есть, но сценарий использования чуть шире, чем предполагал оператор. Ладно, с этим можно жить.

А дальше начинается самое интересное — ответы API.

Например, регулярно прилетает 413 Request Too Large. В запросе — несколько PDF-документов на подпись. Да, их семь. Но каждая PDF весит меньше 500 КБ. В сумме — около 3,5 МБ. Не 300. Не 30. Три с половиной. И, конечно же, в документации ни слова про лимиты. Вообще ни слова. Просто «413». Дальше думай сам.

Другой пример — прилетает 5xx. Ну окей, серверная ошибка. Но в теле ответа при этом очень подробно описано, почему сервер «упал». Я, честно говоря, такое видел впервые. По логике это чистая 4xx — некорректные данные или состояние запроса. Но нет, это 5xx, потому что… потому что так.

Иногда прилетают ошибки вообще без чёткой классификации, и единственная реакция команды — саркастичные комментарии в коде и скриншоты в чате. Не потому что разработчики злые. А потому что ни человек, ни машина не могут понять, что именно произошло и что с этим делать дальше.

И вот здесь у меня всегда возникает один и тот же вопрос:
а мы вообще помним, что с API работают люди?

Да, формально API — это интерфейс «машина-машина». Но на другом конце почти всегда есть разработчик, аналитик, интегратор. Человек, который пытается понять:
— это моя ошибка?
— это ограничение сервиса?
— это временный сбой?
— можно ли ретраить?
— нужно ли писать в саппорт и ждать три дня?

Когда ответ выглядит как «413 Request Too Large» без указания лимитов — это не техническая ошибка. Это провал в developer experience. Когда сервер возвращает 5xx с текстом «потому что данные не такие» — это не архитектура. Это отсутствие заботы о пользователе.

Я всегда стараюсь делать свои API так, чтобы ошибка помогала диагностировать проблему. Не просто код, а контекст: какой лимит, какое поле, какое ожидание нарушено, что можно сделать дальше. Потому что иначе вы перекладываете свою неопределённость на чужую команду.

И вот тут мы снова возвращаемся к теме, которую много обсуждали на курсе по Technical Product Management — developer experience. Он не появляется сам. Его не создаёт документация «для галочки». Его создаёт мышление: относиться к пользователям API так же, как к любым другим пользователям продукта.

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

И да, аналитик и технический продакт здесь нужны не для того, чтобы «описать контракт». А для того, чтобы задать простой человеческий вопрос:
а удобно ли этим вообще пользоваться?