В обзоре API объясняется, что можно делать при помощи API (включая бизнес-цели высокого уровня, потребности рынка или болевые точки, которые он решает), для кого предназначен API. Обзор может содержать и другую вводную информацию.
Цель обзора API
Слишком часто (возможно, потому что контент часто пишется разработчиками) API документация быстро теряется в технических деталях, даже не объясняя четко, для чего используется этот API. Не стоит забывать об общей цели и бизнес-целях API, распаляясь на конечные точки.
Обзор API предоставляет пользователям верхнеуровневое понимание системы. Такое понимание имеет решающее значение для того, чтобы охватить систему в целом, позволяет деталям вписываться в более широкие концептуальные рамки.
Чтобы получить представление о том, что такое API, пользователи начинают с верхнего уровня, получают представление, о чем идет речь из заголовка и описания, а затем переходят к более подробной информации. такой обзор предоставляет начальную ориентацию для пользователя.
В обзоре перечисляются распространенные бизнес-сценарии, в которых может быть полезен API. Эти сценарии предоставляют пользователям контекст, в котором они нуждаются, чтобы оценить, соответствует ли API их потребностям.
Имейте в виду, есть тысячи API. Если люди просматривают ваш API, их первый и самый неотложный вопрос: “какую информацию он возвращает? Является ли эта информация актуальной и полезной для моих нужд?””
Пояснение проблем рынка, которые решает API
В статье 20 основных причинах неудачи стартапов одной из главных причин неудач стартапов является их неспособность решить рыночную проблему. Авторы объясняют:
Этот обзор посвящен проблеме рынка, которую решает API. Если API не работает, скорее всего, это из-за того, что он не решает проблему рынка.
Обзор API обычно размещается на главной странице API. Домашняя страница (начало документации) является хорошим местом для размещения такого обзора, потому что в таком обзоре также определяется и своя аудитория. Понимание аудитории поможет правильно сориентировать контент в документации по API.
Примеры обзора API
Приведем несколько примеров обзоров API:
SendGrid
Обзор Sendgrid начинается с двух ключевых разделов: «Что такое SendGrid?» И «Для кого SendGrid?». Отличный простой подход. Даже в описании того, что такое SendGrid, авторы не предполагают, что все знают, что такое SMTP-провайдер, поэтому разместили ссылку на дополнительную информацию. В целом, примерно за 10 секунд можно получить представление о том, что такое API SendGrid.
Lyft
Обзор API Lyft начинается аналогичным образом, с разделов «Что такое Lyft?» И «Зачем использовать Lyft в качестве разработчика». Их домашняя страница также предоставляет информацию о доступе, ограничениях скорости и регулировании, а также тестировании. Авторы Lyft также признают, что у каждого домена технологий есть свой собственный жаргон, поэтому они заранее предоставляют глоссарий.
IBM Watson Assistant
IBM Watson Assistant начинается с краткого описания сервиса, после чего следует общая схема системы и сводная информация о том, как ее реализовать. Включение диаграммы API дает пользователям хорошее представление о том, чего ожидать, например, об уровне сложности и времени, которое потребуется для внедрения API.
👨💻 Практическое занятие с обзором API
В своем найденном опен-сорс проекте найдем раздел Обзор API и ответим на следующие вопросы:
- Есть раздел Обзор API в документации?
- Объясняет ли обзор, для кого предназначен API?
- Обозначает ли обзор потребность рынка или бизнес-проблему, которую решает API?
- Какие вопросы у вас остались об API после прочтения обзора?
- Как обзор переходит к разделу Начало работы или другим первым шагам с API?