Ты - продакт в крупном интернет-магазине, и у тебя есть крутая новая идея функции для службы поддержки. Вы будете автоматически исправлять текст, написанный агентами поддержки, и делать так, чтобы сообщения от лица компании звучали кратко и профессионально. Все орфографические ошибки, опечатки и прочее будут исправлены в один клик.

Прежде чем бежать с этой замечательной идеей к команде разработчиков, тебе надо быстро проверить, какой функционал уже доступен. Тогда ты сможешь написать понятный и корректный тикет в JIRA: получить эти данные, отправить их в этот API, получить ответ от API, использовать его в продукте для выполнения X (позже посмотрим, что именно там будет), провести эксперимент, профит!

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

SШаг 1. Начни с поиска нужной функциональности (внутри компании или в Google). В нашем случае это будет поиск по запросу «Translate API», и мы выбираем сервис от DeepL. Вот ссылка на их документацию.

Шаг 2. Прочитай описание эндпоинта API, который лучше всего подходит под требования. У DeepL есть есть несколько эндпоинтов (/translate text, translate documents, etc), но нам понадобится “Improve text”. Кажется, что пример делает ровно то, что нам нужно - исправляет кривой текст:

Шаг 3. Определи входные параметры, wкоторые мы должны отправить из нашего продукта в DeepL API.
Изучи документацию и попробуй ответить на следующий вопрос:

Как видно в разделе «Запрос», есть один обязательный параметр (text) и несколько необязательных (tone, writing_style, target_lang). Интересно! Это значит, что мы можем исправить опечатки и сделать текст наших агентов немного более «теплым». Еще раз посмотри в документацию и попробуй самостоятельно ответить на следующий вопрос:

Глядя в документацию, я вижу, что первый вариат как раз подходит.

Шаг 4. Определи выходные параметры (то, что мы получим от API и используем в продукте). В этом случае API возвращает улучшенный текст в параметре… text. Наши разработчики могут взять его из API и использовать в продукте: скорее всего, мы захотим еще показать этот текст агенту поддержки, чтобы он его проверил перед отправкой клиенту.

Шаг 5. Определи возможные ошибки (чтобы подготовить продукт к тому, что ответ не всегда будет успешным). В данном случае все довольно просто: если мы правильно зададим параметры, то, скорее всего, получим улучшенный текст. Если нет, то API вернет ошибку, и нам нужно будет сказать агенту поддержки: «Прости, тебе придется самому поправить сообщение».

Шаг 6. Проверь, есть ли у API какие-то особенности. Например, является ли API асинхронным? Может ли он возвращать неочевидные результаты? Или есть цепочка вызовов: служба A вызывает службу B, которая вызывает службу C, которая, наконец, вызывает DeepL API? В этом случае тебе придется немного покопаться в нем и построить Sequence Diagram. Если захочешь в этом попрактиковаться, заходи на наш прикладной курс. Ну а в данном случае API достаточно простой, так что ничего дополнительно делать не нужно.

Шаг 7. Наконец, ты готов писать dev story для команды: что/зачем подключать, какие параметры отправлять, что получать обратно и как это использовать в продукте. Супер!

Всего 15 минут исследования продукта, и вот ты уже можешь поставить четко определенную задачу для своей команды (или для ИИ-генераторов кода Replit/Bolt и прочих, если ты один из тех крутых ребят, которые любят поиграться с новой технологией).

Конечно, по теме API еще много чего можно сказать и много в чем попрактиковаться, и один пример не сделает из тебя гуру (но пять к этому приблизят!). Если ты любишь получать новые навыки в манере вопрос/ответ, как мы сделали в этой статье, то у нас есть самостоятельный симулятор "Технологии для продакта, где ты решаешь задачи с виртуальными коллегами.