🚀 10 Капитанских правил для REST-API в Финтехе 🚀

Привет всем!

На протяжении многих лет работы в IT я сталкиваюсь с "детскими болезнями" API. Не смотря на то, что написана масса статей, сделано множество докладов, и даже изданы книги, но проблема качества API возвращается как бумеранг. API — это лицо компании. И к сожалению, очень часто, вместо того чтобы сделать его прекрасным, мы делаем его "помятым". Вот мои 10 капитанских правил, как сделать API лучше:

1️⃣ Понятность названий параметров: Каждый параметр должен однозначно объяснять своё предназначение и формат. Пример: параметр "visibility_flag", кажется должен быть булевым (true/false). Однако часто такие параметры могут быть представлены как int со значениями 0, 1, 2, 3... Это создаёт путаницу и уменьшает читаемость API.

2️⃣ Использование префикса для булевых переменных: Для булевых переменных используйте префикс 'is', например, 'is_visible'. Это сразу делает понятным, что переменная имеет два состояния: истина (и true = видимо) или ложь, и упрощает работу с кодом.

3️⃣ Ясное описание происходящего: Если можно объяснить ситуацию словами — делайте это. Вместо того чтобы заставлять пользователя дешифровать числовые значения в 'invisibility_reason', лучше сразу указывать причину: 'blocked', 'fraud', 'no money'. Это делает API более дружелюбным и понятным.

4️⃣ Прозрачность ошибок: Не заставляйте пользователей разбираться в сложных таблицах для понимания ошибок. Ошибки должны быть понятны и просты для интерпретации, чтобы пользователи могли быстро находить и исправлять проблемы. Самый странный протокол в моей жизни содержал 57 печатных страниц с расшифровкой кодов ошибок.

5️⃣ Полная информация об ошибках: Если в процессе выполнения запроса обнаружено несколько ошибок, сообщайте о всех одновременно. Это позволяет пользователям быстрее и эффективнее устранять проблемы. Пример: отправлены данные пользователя. Но одно из обязательных полей пропущено, а в паспорте нехватает цифры. Если обе проверки выполняются на API (а скорее всего - да, так как это валидация данных) - отдайте сразу обе ошибки и о нехватке данных, и об ошибке в номере паспорта.

6️⃣ Отсутствие дублирующих параметров: Избегайте создания параметров с похожими названиями и разной логикой. Пример: 'is_visible' и 'visible_flag'. Если хотите в поле 'visible_flag' поместить причину - назовите 'visibility_reason', если "буль" передающий информацию о ручной установки видимости из админки 'is_visible_manual'.

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

8️⃣ Продуманность структуры данных: Лучше заранее подумать о данных, которые могут понадобиться в будущем (в части сущностей, где вы не main система), чем впоследствии их добавлять. Например, клиент-создается на стороне Мерчанта, вы только обогащаете его параметрами. Но клиент может иметь «галочку», которая вам если и понадобится, то не раньше чем через год. При большой пользовательской базе и части процессов идущих напрямую через вас, добавление параметра через год, может стоить дорого.

9️⃣ Изолированность данных в методах: Убедитесь, что каждый метод работает с данными только одной сущности. Это облегчает понимание и поддержку API. Не стоит в клиентские методы прокидывать параметры счета и наоборот. Если признак тестовости у клиента, а счет не имеет признака тестовости, то методы аккаунтов не должны содержаить параметь 'is_test'.

🔟 Подробные описания кодов: Если ваш API использует специфичные числовые коды, обязательно предоставьте рядом текстовое описание. Это поможет другим разработчикам и поддержке быстрее разобраться в работе системы.

Надеюсь, эти правила помогут сделать наш API не просто функциональным, но и удобным и приятным в использовании!

Сегодня на конфе Анализ и управление в ИТ проектах. Мой доклад через 40 минут, а пока что поучаствовал у Алены Ивахновой в мастер классе по работе с ИИ.
Очень крутой материал, структура промптов, примеры задач по расписыванию предметной области, бизнес процессов и диаграмм. ChatGPT готов помогать нам все больше и больше

Помогаю Дмитрию Кучме из Коруса провести для аналитиков игру с построением БПМН процессов из настоящих деревянных элементов. Никаких вам Визио и Камунд!

Всем доброго вечера! К сожалению, в эти выходные провести мастер-класс не получится , потому что из России я помимо положительных впечатлений и кучи мерча привез еще и какой то гадкий вирус.
Эту неделю я с ним доблестно борюсь, так что сил на МК не хватает. Пока план - сдвинуть на две недели, так что stay tuned!
Всем здоровья!

Ребята из Flow сегодня опубликовали мой доклад с мартовской конференции.
Смотрите и наслаждайтесь!
А если захотите сделать так же (я и про требования и про выступление), то приходите ко мне на сессии менторинга

#видеозаписи

Начинаем постепенно публиковать записи весенней Flow!

Каждый четверг будем открывать по одному докладу. И сегодня — один из самых просматриваемых.

Всем бодрого понедельника.
Продолжаю копать вглубь в ДДД. На этот раз посмотрел выступление и прочитал статью Максима Цепкова.
И то и другое, как обычно великолепны. Максим в коротком формате умудряется выдать огромный по смыслу объем информации, я пока так не умею.
А если по существу, то очень понравилась мысль про ДДД как инструмент новой модели построения систем, в противопоставление классическому водопаду.
Рассказ про мышление объектами реального мира и их отражение в коде в целом классический, почерпнул пару практических примеров.
Если собираетесь расти в сторону функциональной и солюшен архитектуры - настоятельно рекомендую

Уже давненько прочитал книжку "50 бизнес моделей новой экономики" от троих известных российских авторов и предпринимателей Михаила Иванова (МИФ), Александрв Горного (инвестор, стартапер), Алексей Черняк (инвестор, основатель Groupon).
Книга построена в формате справочника и описывает 50 крутых стартапов ставших единорогами (более $1 млрд капитализации), сопровождаемых комментариями авторов, сводной аналитикой и описанием собственно бизнес модели, как одной из составляющих успеха.
Если смотрите в сторону своего стартапа (а я внезапно смотрю в эту сторону) или идете в продуктовый менеджмент, то настоятельно рекомендую почитать. Читается быстро и легко.

Сегодня пост тщеславия. Выкладываю несколько фоток со своего доклада на Аналист дейз и презентацию выступления "Почему из аналитиков плохие продакты".

Доброго вечера! Накину немного в вечер пятницы (а когда же еще)😈
Я все не оставляю своего любимого конька про Agile и самоорганизующуюся команду высокомотивированных профессионалов.
Для многих Agile в силу его насильного внедрения на уровне карго культа в организациях стал просто ругательным словом, что меня заставляет сильно грустить.
На первый взгляд кажется, что это понятный концепт, потом, что оно невозможно. Но если детально подумать, что под большинство концептов Agile можно найти логичные объяснения.

Возьмем, например, спринты. Зачем это нужно?
Все очень просто: есть закон Паркинссона: Всякая работа занимает ровно столько времени, сколько на нее отведено или больше.
Соответственно, если мы искусственно создаем ограничение в виде спринта, то сотрудники и будут целиться в пределы этого спринта.
Ведь вы знаете, что в конце спринта нужно показать результаты своей работы. Именно поэтому, кстати, Скрам настаивает на обязательном ритуале обзора результатов спринта, чтобы этот дедлайн был ощутимым.

Плюс еще одной важным плюсом работы по спринтам можно назвать привычку или, если угодно, рутину.
Для каждого человека очень важны ритуалы. Утренний кофе, душ, зарядка, медитация. Я это понял, глядя на своего ребенка, которому, чтобы спокойно пойти в кровать нужно выполнить несколько обязательных риталов. Если их не выполнить, то можно словить нехилую истерику.
То же самое и для взрослых людей. Нам важно "заземляться", рутина помогает нашей голове расслабляться и делать какие то операции на автомате, выстраивая из них последовательность, снижать уровень стресса и потребления мыслетоплива.
И в работе от этого никуда не деться: ты знаешь, что сегодня дейлик, к нему нужно подготовить ответы на вопрос, а завтра релиз, послезавтра демо результатов. Тебе не надо об этом задумываться.
В целом, все больше убеждаюсь, что гибкие методологии разработки они в первую очередь про здравый смысл.
А как вы относитесь к Agile и его производным?

Интересная заметка, которая в целом подтверждает то, что я рассказываю в своих выступлениях.
Если вы умеете работать головой, то ИИ только ускорит свою работу, а вот если основная ценность вашей работы в написанных бумажках, то ИИ скорее всего доставит вам много проблем

ИИ-заменитель

Survey Monkey изучила 1000+ маркетологов стартапов. Две трети ищут данные, которые у них уже есть. Половина не понимает, почему аудитория не конвертируется. Треть не знает, чего хотят потребители. Зато 88% заморочены тем, как внедрить ИИ в свою маркетинговую стратегию. У 72% это получается хреново.

Вывод прост: ИИ заменяет кофеин и энергетики, но не мозги.