API, документация и портал разработчика

На протяжении многих лет работы в ИТ я сталкиваюсь с «детскими болезнями» API. Не смотря на то, что написана масса статей, сделано множество докладов, и даже изданы книги, но проблема качества API возвращается как бумеранг. 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. Часто API страдает от недостаточной ясности, даже при хорошем проектировании из-за отсутствия качественной документации.

🤝Контракт: Это основа любого протокола. Этот документ разъясняет, кто участники взаимодействия, на основании чего строится это взаимодействие. Здесь очерчиваются зоны ответственности сторон. Особенно важно это, если у вас несколько потребителей, и они не все одноранговые. В контракте также описываются регламенты обновлений, правила совместного тестирования, порядок проведения технических работ.

🔖Словарь: Вводите чёткое определение терминов, таких как "Merchant" или "Client", чтобы избежать недопонимания. Это упростит интеграцию новых пользователей и поможет избежать многих ошибок.

📈 Бизнес-описание методов: Просто перечисления параметров и примеров недостаточно. Необходимо описать, как именно вы спроектировали протокол, что делает каждый метод, какое поведение системы ожидается, что делать в случае успеха, и какие рекомендации при ошибках. Если есть рекомендованный Customer Journey Map (CJM), его тоже стоит приложить.

🚫 Описание ошибок и рекомендации по их обработке: Предоставляйте не только коды ошибок, но и чёткие инструкции о том, как их обрабатывать. Вы не можете диктовать какие интерфейсы будут у конечного пользователя, но вы можете выдать рекомендации и рекомендуемые тексты к ошибкам. Это особенно актуально, если по части ошибок, сопровождает клиента не потребитель, а ваша компания (частый кейс для платежных систем).

🥸 Справочники: Содержат всю необходимую справочную информацию, включая алгоритмы проверки данных. Именно тут должен быть описан алгоритм проверки валидности ИНН или перевод кодов сторонней системы (например МПС) в ваши коды ошибок. Тут же могут быть отражены, рекомендуемые тексты для писем/PUSH/sms конечным пользователям, если их отправляет потребитель.

🧑‍💻 Сценарии тестирования: Предоставьте полный набор тестов, который позволит потребителю убедиться в корректности интеграции с вашим API.

📑Лист изменений: Документируйте все изменения в API, указывая версию, список изменений, статус внедрения и планируемые даты релизов.

🛠Технический лист: Описывает процедуры получения токенов, их отзыва и требования к безопасности и хранению данных.

⁉FAQ: Ответы на частые вопросы и описание типичных ошибок, с которыми уже сталкивались пользователи, а также контактная информация для обратной связи.

А теперь пора ответить на вопрос: где это всё размещать и как с этим работать? Ответ прост и лежит на поверхности — создание портала разработчика.

Думаю, что коллегам из финтеха хорошо знаком пример такого портала — PayPal Developer. Шикарно оформленный и информационно-наполненный ресурс, на который стоит ровняться!

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

Основная цель портала — обеспечить единую точку доступа ко всей необходимой информации для внутреннего и внешнего использования вашей системы. Это особенно важно для компаний, предоставляющих решения на условиях white label. Портал упрощает интеграцию с вашими продуктами и способствует развитию партнёрских отношений.

1 Протоколы API и их документация

2 Интерактивная "песочница" для тестирования

3 Справочные материалы, форумы и сообщества поддержки

4 Описание end-to-end тестов, включая тестовые наборы данных

5 SDK, демо-версии сайтов, no-code решения, тестовые админки

6 Пользовательские инструкции, договоры оферт

📌Централизация информации — все данные о продукте собраны в одном месте.

🛠 Упрощение интеграции — сторонним разработчикам легче работать с вашим API благодаря хорошо структурированной документации и инструментам.

🤝 Снижение нагрузки на поддержку — хорошо документированная информация уменьшает количество запросов в службу поддержки.

👋Привлечение новых клиентов — доступный и понятный портал привлекает разработчиков, что способствует росту использования ваших продуктов.

💬 Обратная связь и развитие — портал позволяет собирать обратную связь и улучшать продукты в соответствии с потребностями пользователей.

Вывод прост: если ваш продукт уже не новичок на рынке и имеет обширную историю, наличие портала разработчика — это не роскошь, а средство для обеспечения удобства работы с вашим API и укрепления вашего бренда среди разработчиков. Если ваш продукт представляет собой "коробку" или предлагается на условиях white label, то наличие такого портала не просто желательно, а почти обязательно.

Да, все что описано в этой статье = "очевидно", но раз за разом мы сталкиваемся с "дурацкими" ошибками и недоработками, которые помогут сэкономить нервы и спасти от инцидентов!