Порталы API DevEx: подробное руководство

1 декабря 2022 г.

Зачем вам нужен портал, если вы хотите обслуживать разработчиков

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

Но именно так многие компании учат людей использовать свои API: они передают стопку документации, ключ API и заканчивают работу. Конечно, эти инструменты важны; без них ваши пользователи застряли на «Go». Но сами по себе эти инструменты не дают пользователям никакого опыта. Это просто. Это тускло. Это опыт, но, вероятно, не ТОТ опыт разработчика, который вы хотите предоставить своим пользователям. Это определенно не восхитительный опыт и не настолько запоминающийся, чтобы рассказывать об этом другим. И этот скучный опыт оказывает существенное влияние на принятие и использование вашего API.

Если в опыт разработчиков недостаточно вложены средства, возникает стандартный набор проблем:

• Средний промежуток времени между регистрацией пользователя и первым успешным запросом превышает один день.
• Ваша команда каждую неделю тратит несколько часов на устранение неполадок, связанных с интеграцией клиентов.
• Среднее количество вызовов API & конечные точки, созданные пользователями, со временем не расширяются.

Результат:

• Уменьшение внедрения и использования API
• Более высокая стоимость поддержки для каждого пользователя.
• Сниженная LTV для каждого пользователя.

Чтобы решить эти проблемы, вам необходимо значительно улучшить DevEx вашего API. Ключом к удобному взаимодействию с пользователями является предоставление пользователям портала API DevEx, благодаря которому ваш API:

• Доступность: отправка запросов API не требует особых усилий.
• Понятный: пользователи могут немедленно получать отзывы об использовании API и самостоятельно устранять неполадки, когда они возникают.
• Используемый: пользователям будет очень просто обнаружить и протестировать новые варианты использования вашего API, которые естественным образом расширят сферу их применения.

Но какие инструменты помогут вам достичь этого? Давайте рассмотрим каждый из вышеперечисленных критериев и обсудим конкретные инструменты, которые могут помочь вам предоставить пользователям API ту DevEx, которую они заслуживают.

Какие инструменты нужны вашему порталу API

Доступно

Сделать API доступным означает максимально упростить для пользователей первый вызов API. 99 % компаний все еще застряли где-то на этом первом этапе.

Ключевые возможности:

• Документация по API. Широко распространено мнение, что документация равняется отличному DevEx. Мы думаем, что документация — это только первый шаг: она важна, но сама по себе она все равно оставит желать лучшего у пользователей вашего API. Документация должна быть исчерпывающей, удобной для навигации/поиска и содержать встроенные фрагменты кода/примеры. В идеале документы должны позволять пользователям опробовать API без каких-либо дополнительных инструментов или настроек. Документация по API также должна различать справку по API (полный список всех конечных точек, параметров, кодов ответов и т. д.) и руководства по использованию (руководства, в которых пользователи шаг за шагом объясняют, как они могут использовать API для выполнения ключевых задач).

* Вход с авторизацией. Если вы хотите предложить разработчикам более персонализированный опыт, авторизация является обязательным условием. Вам нужно знать, кто кто такой, прежде чем вы сможете выдать ему ключ API и начать давать ему инструменты, которые помогут ему понять и отследить его использование. Конечно, вход в систему должен управляться одной общей службой идентификации, например. auth0 или другая система записи — например, вы не хотите создавать отдельную систему управления пользователями для своего приложения и API.

* Управление ключами API. Никто не хочет заполнять форму ввода и ждать, пока служба поддержки рассмотрит ее, прежде чем начать работу с API. Если у разработчика нет возможности создавать ключи самостоятельно, большинство из них никогда не превратятся в пользователей вашего продукта. К тому времени, когда кто-то рассмотрит свой запрос на доступ, он перейдет к новому приоритету или найдет альтернативное решение. Если API взаимодействует с конфиденциальными данными, а процесс проверки является юридическим требованием для рабочих учетных данных, разрешите пользователям предоставлять ключи песочницы без проверки (подробнее о песочницах ниже).

Понятно

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

Ключевые возможности:

• Просмотр запросов API. При отладке ничто не заменит возможность пошагового выполнения действий. Средство просмотра запросов позволяет вашим пользователям просматривать полный список запросов, которые они отправили в ваш API, не создавая дополнительной работы для вашей команды по извлечению журналов, отправке снимков экрана по электронной почте или в Slack или переходу на вызов Zoom. Без средства самообслуживания для просмотра запросов неработающие интеграции ухудшают работу API и приводят к оттоку клиентов. Средство просмотра запросов должно предоставлять пользователям возможность фильтровать по времени, коду ответа, конечной точке и т. д. В идеале пользователи могут редактировать и воспроизводить запрос для быстрой отладки.

* Метрики использования API. Средство просмотра запросов полезно для разработчиков, только если они знают, что есть проблема, которую нужно исследовать. Вот почему важно отображать ключевые показатели использования в режиме реального времени, чтобы пользователи знали об общем состоянии своей интеграции. Показатели использования должны делать упор на отчеты об ошибках и существенных изменениях в использовании, чтобы ваши пользователи могли принять меры по устранению любых ошибок или непреднамеренных изменений.

• Страница статуса API. Разработчикам нужно место, чтобы проверить, не происходит ли простоя API. Нет ничего более разочаровывающего, чем необходимость отправлять электронное письмо компании с вопросом «работает ли ваш API?» Страница состояния API обеспечивает прозрачность, а прозрачность важна для укрепления доверия пользователей.

Полезно

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

Ключевые возможности:

• Клиентские SDK. Вам нужно встретиться со своими разработчиками там, где они уже есть. Предоставление клиентских SDK облегчает разработчикам начало работы с вашим API, поскольку они знакомятся с их любимым языком и значительно сокращают объем шаблонного кода, который им необходимо написать. Это особенно верно, если ваши SDK могут обрабатывать аутентификацию, разбиение на страницы, повторные попытки и другие действия. Поэтому они отлично помогают максимизировать вашу аудиторию при минимальных затратах на поддержку. Но недостаточно иметь SDK, очень важно, чтобы SDK были удобными для разработчиков, а это означает, что они идиоматичны для языка и удобочитаемы для человека. К сожалению, создание клиентских SDK непомерно дорого обходится большинству команд API, поскольку их необходимо создавать и обновлять вручную. Хотя генераторы с открытым исходным кодом существуют, SDK, которые они выдают, часто содержат ошибки и не являются эргономичными.

* Рабочие модули API. Мы думаем о модулях Runbook как о действующих руководствах по использованию. Они шаг за шагом проводят пользователей через процесс использования вашего API для выполнения определенных задач, а также показывают актуальные запросы API в режиме реального времени. Это помогает сосредоточить внимание разработчиков на ключевых вариантах использования, необходимых для завершения интеграции API. Ваши клиенты могут использовать их для расширения использования вашего API. Как разработчику API, модули runbook также помогают вам понять зрелость вашей клиентской базы: вы можете начать понимать использование API в качестве воронки клиентов и начать измерять, где и почему пользователи выбывают из воронки.

* Песочница API. Вероятно, ничто так не помогает при внедрении, как предоставление разработчикам простого способа поиграть с вашим API. Песочница может позволить потенциальным пользователям использовать ваши API без необходимости регистрации учетной записи. Разработчики с большей вероятностью будут доверять API, если они видели, как он работает, прежде чем им нужно будет передать свою информацию. И песочница может дать существующим пользователям возможность учиться на практике и без какого-либо риска повреждения рабочих процессов. Это позволяет пользователям легко расширять варианты использования вашего API.

Как стать лучшим в своем классе: построить или купить?

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

Но, как скажет вам любой продакт-менеджер или инженер, знание того, что строить, — это только начало. Поиск ресурсов, необходимых для строительства, — настоящая битва. Отличный DevEx чрезвычайно важен для успешного API, но создание всего вышеперечисленного требует огромных ресурсов, требует значительного постоянного обслуживания и, вероятно, не является основной компетенцией для вашей организации. Поэтому инвестиции в Developer Experience запланированы на следующий квартал.

Таким образом, почти для каждой компании инвестирование в лучшее в своем классе решение имеет больше смысла. С порталом API DevEx от такой компании, как Speakeasy, ваши клиенты получают первоклассный опыт разработки API за несколько дней, а не за кварталы, план развития вашего продукта оказывает незначительное влияние, а вашим инженерным командам не нужно изобретать велосипед.

Кроме того, наш продукт разработан с учетом максимальной гибкости, предоставляя вам лучшее из обоих миров. Каждый инструмент на нашем портале API DevEx является компонентом React, и его можно настраивать, маркировать и расширять по мере необходимости. Точно так же наша платформа может быть размещена самостоятельно или работать в нашем Speakeasy Cloud в зависимости от ваших требований.

Заключительные мысли

Долгое время компании могли обходиться нестандартным подходом к разработчикам, но ситуация начинает меняться. Опыт разработки теперь получает то внимание, которого он заслуживает, и мы быстро приближаемся к переломному моменту. То, что раньше считалось замечательным DevEx, становится основным продуктом для разработчиков.

Мы знаем, что DevEx игнорируется не потому, что компании не видят ценности. Скорее, это результат болезненных решений по расстановке приоритетов. Вот почему существует Speakeasy. Мы не хотим, чтобы кто-либо когда-либо шел на этот компромисс. Со Speakeasy вы можете создать и запустить лучший в своем классе компонуемый портал для разработчиков за считанные минуты. Если вы хотите узнать больше, присоединяйтесь к нашей бета-программе или общайтесь с нами в Slack!

Первоначально опубликовано здесь.

---

Оригинал