ПРО АНАЛИТИКА | СИСТЕМНЫЙ АНАЛИТИК | АЛЕКСАНДР НЕЗДЕМИНА
Образование · 15 июня 2026 г.
ЧТО ЗАБЫВАЮТ ПРИ ПРОЕКТИРОВАНИИ API? — 15 июня 2026 г. в 07:40:33.067
ЧТО ЗАБЫВАЮТ ПРИ ПРОЕКТИРОВАНИИ API? Представьте, что вы спроектировали метод, отдали его в разработку и даже докатили до прода. Дальше API-шка живет какое-то время и все вроде хорошо, а потом вы или решили сделать в ней доработку, или поддали нагрузки и вдруг что-то сломалось. И такое, часто бывает из-за того, что какие-то мелочи на старте, при проектировании, не учли. И сегодня поговорим, про четыре таких "мелочи", которые встречаю чаще всего. ➖➖➖ 1️⃣ Идемпотентность Все же знают, что метод POST не идемпотентный? Но при проектировании вечно забывают про то, что нужно продумать поведение при ретраях или других сценариях. Я за свою карьеру повидал очень много постановок на разработку и угадайте в скольких из них было расписано детально про идемпотентность? По ощущениям, в процентах 2-5. Но почему важно продумывать этот кейс? Потому что когда у вас маленькая нагрузка, все шустро работает, это может и не стрельнуть в ногу, но если у вас появляется большое количество пользователей, сервисы начинают чуть дольше отвечать, то в этом случае есть риск получить дубль. И хорошо если это дубль записи в БД, а если двойное списание деньжат? Короче, неприятно. 2️⃣ Неизменность контракта для потребителей Например, один из частых кейсов, когда ваш сервис стоит посередине и у вас, как вам кажется, 1-2 потребителя и тут вам надо в контракте что-нибудь поменять или порефачить. Вы оповещаете своих потребителей, меняете, синкаетесь по доработкам. И тут прибегает еще ворох потребителей о которых вы даже не знали. Сюрприиииз 😐 Чтобы такого никогда не произошло, или не меняйте контракт и делайте версионирование, или ведите табличку с потребителями. 3️⃣ Пагинация Пагинация - вещь про которую забывают начинающие и когда проектируют, то не смотрят на количество возвращаемых данных. И даже наличие массива объектов их не смущает, а из-за этого при реальной нагрузке, когда вам вернётся 100500 строк, можно получить "500 Internal Server Error". Лечится просто: отдавайте данные частями, через offset и limit, или через page и size. 4️⃣ Трассировка Про неё обычно вспоминают, когда на проде уже горит и надо срочно понять, где в цепочке Ui -> middle -> кафка -> бэк потерялся запрос, а вы открываете логи и там 100500 похожих вызовов, в которых ничего не найти. А если прокинуть traceId, то это сэкономит кучу времени, так как вы сразу увидите всю цепочку, поэтому, если проектируете интеграцию с нуля, сразу закладывайте трассировку. ➖➖➖ Подытожу Обычно ошибки при проектировании возникают не в каких-то сложных, а как раз в простых кейсах, которые лежат прям перед носом, поэтому обращайте на них внимание и продумывайте свои контракты более тщательно.