В какой-то момент я понял, что про партнёрства и интеграции мы слишком часто говорим абстрактно — на уровне «API есть, документация есть, поехали». А вот про реальное качество этих API и про то, как с ними живётся, говорим куда реже.
Вспомнилась история из практики. Работали мы с одним итальянским провайдером квалифицированной электронной подписи. По европейским меркам — вполне себе серьёзный игрок, что-то вроде местного аналога Контура. И здесь сразу важный нюанс: в Европе электронная подпись используется не только для фиксации неизменности документа и авторства подписанта, но и как инструмент KYC. То есть это уже не совсем «каноничный» кейс подписи, а такой сайд-кейс. Формально подпись есть, но сценарий использования чуть шире, чем предполагал оператор. Ладно, с этим можно жить.
А дальше начинается самое интересное — ответы API.
Например, регулярно прилетает 413 Request Too Large. В запросе — несколько PDF-документов на подпись. Да, их семь. Но каждая PDF весит меньше 500 КБ. В сумме — около 3,5 МБ. Не 300. Не 30. Три с половиной. И, конечно же, в документации ни слова про лимиты. Вообще ни слова. Просто «413». Дальше думай сам.
Другой пример — прилетает 5xx. Ну окей, серверная ошибка. Но в теле ответа при этом очень подробно описано, почему сервер «упал». Я, честно говоря, такое видел впервые. По логике это чистая 4xx — некорректные данные или состояние запроса. Но нет, это 5xx, потому что… потому что так.
Иногда прилетают ошибки вообще без чёткой классификации, и единственная реакция команды — саркастичные комментарии в коде и скриншоты в чате. Не потому что разработчики злые. А потому что ни человек, ни машина не могут понять, что именно произошло и что с этим делать дальше.
И вот здесь у меня всегда возникает один и тот же вопрос:
- это моя ошибка?
- это ограничение сервиса?
- это временный сбой?
- можно ли ретраить?
- нужно ли писать в саппорт и ждать три дня?
Когда ответ выглядит как «413 Request Too Large» без указания лимитов — это не техническая ошибка. Это провал в developer experience. Когда сервер возвращает 5xx с текстом «потому что данные не такие» — это не архитектура. Это отсутствие заботы о пользователе.
Я всегда стараюсь делать свои API так, чтобы ошибка помогала диагностировать проблему. Не просто код, а контекст: какой лимит, какое поле, какое ожидание нарушено, что можно сделать дальше. Потому что иначе вы перекладываете свою неопределённость на чужую команду.
И вот тут мы снова возвращаемся к теме, которую много обсуждали на курсе по Technical Product Management — developer experience. Он не появляется сам. Его не создаёт документация «для галочки». Его создаёт мышление: относиться к пользователям API так же, как к любым другим пользователям продукта.
Неважно, это внутренние команды или внешние партнёры. Если у них после интеграции остаётся ощущение раздражения и беспомощности — значит, продукт работает плохо. Даже если формально «всё по спецификации».
И да, аналитик и технический продакт здесь нужны не для того, чтобы «описать контракт». А для того, чтобы задать простой человеческий вопрос:
а удобно ли этим вообще пользоваться?
Дискуссия