Последнее обновление 21.05.2023 — Василий Иванов
Такие читатели, как вы, помогают поддерживать MUO. Когда вы совершаете покупку по ссылкам на нашем сайте, мы можем получать партнерскую комиссию. Читать далее.
Все больше организаций используют возможности API для оптимизации своего бизнеса. API стали способом раскрыть ценность и предоставить дополнительную услугу.
Несмотря на их общую популярность, не все API пользуются успехом. Принятие и использование API во многом определяет его успех. Чтобы повысить уровень принятия, ваш API должен быть простым для поиска и использования.
Лучший способ сделать это — подробно задокументировать ваш API. Это включает в себя детализацию критических компонентов, чтобы их было легче понять. Узнайте о некоторых компонентах, которые следует включить в документацию по API.
Что такое документация по API?
Документация API — это технический контент, подробно описывающий API. Это руководство, содержащее всю информацию, необходимую для работы с API. Документ охватывает жизненный цикл API и инструкции по интеграции и использованию его компонентов.
Документация API охватывает описания ресурсов, конечные точки, методы, запросы и примеры ответов. Он также может включать практические руководства и учебные пособия, показывающие пользователям, как его интегрировать. Изучение каждого раздела дает пользователям четкое представление об интеграции и использовании API.
Такие редакторы, как Google Docs, когда-то широко использовались для профессиональной документации по API. В настоящее время существуют более продвинутые инструменты, такие как Document 360, Confluence и GitHub Pages. Эти инструменты помогают интегрировать текст и код для упрощения рабочих процессов.
1. Обзор и назначение API
Первым шагом в документировании API является информирование пользователей о том, что это такое. Включите информацию о типе ресурсов, которые он предоставляет. API обычно имеют различные ресурсы, которые они возвращают, поэтому пользователь может запросить то, что ему нужно.
Описание краткое, обычно от одного до трех предложений, описывающих ресурс. Опишите доступный ресурс, конечные точки и методы, прикрепленные к каждой конечной точке. Как разработчик API вы лучше всего описываете его компоненты, функциональность и вариант использования.
Вот пример описания Airbnb API:
2. Методы аутентификации и авторизации
API-интерфейсы обрабатывают тысячи запросов и огромные объемы данных. Аутентификация — это один из способов защитить данные вашего API и пользователей от хакеров. Аутентификация API проверяет личность пользователя и предоставляет ему доступ к ресурсам.
Существует несколько способов обеспечения безопасности конечных точек. Большинство API используют ключ API. Это строка символов, которую пользователь может сгенерировать на веб-сайте и использовать для аутентификации.
Документация по API должна указывать пользователям, как аутентифицировать и авторизовать свои удостоверения. На следующей диаграмме показаны данные аутентификации Twitter API.
3. Конечные точки, шаблоны URI и методы HTTP
В этом разделе продемонстрируйте, как получить доступ к ресурсу. Конечные точки показывают только конец пути, отсюда и их название. Они показывают доступ к ресурсу и методы HTTP, с которыми взаимодействует конечная точка, а именно GET, POST или DELETE.
Один ресурс, вероятно, имеет множество конечных точек. У каждого свой путь и метод. Конечные точки обычно имеют краткое описание своего назначения и шаблон URL.
В следующем примере кода показана конечная точка пользователя GET в Instagram.
GET /me?fields={fields}&access_token={access-token} 4. Форматы запросов и ответов
Вы должны задокументировать форматы запроса и ответа, чтобы пользователь знал, чего ожидать. Запрос — это URL-адрес от клиента, запрашивающего ресурс, а ответ — это обратная связь от сервера.
Ниже приведен пример запроса, который вы можете отправить в LinkedIn API.
GET https://api.linkedin.com/v2/{service}/1234 И вот пример ответа, который он может вернуть:
{
"id": 1234,
"relatedEntity": "urn:li:relatedEntity:6789"
} 5. Параметры и заголовки
Вы также должны задокументировать параметры ваших конечных точек, которые являются параметрами, которые вы можете передать им. Параметрами могут быть идентификатор или число, указывающее количество или тип данных, возвращаемых в ответ.
Существуют различные типы параметров, включая параметры заголовка, пути и строки запроса. Конечные точки могут содержать различные типы параметров.
Вы можете включить некоторые параметры в качестве заголовков HTTP-запроса. Обычно они предназначены для аутентификации, например ключ API. Вот пример заголовка с ключами API:
headers: {
'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}
Вы включаете параметры пути в тело конечной точки прямо в URL. Они показывают пользователю, как и где размещать параметры и как будет выглядеть ответ. Слова в фигурных скобках являются параметрами.
Вы также можете использовать двоеточие или другой синтаксис для представления параметров пути.
/service/myresource/user/{user}/bicycles/{bicycleId} При использовании параметров запроса необходимо поставить вопросительный знак (?) перед запросом на конечной точке. Разделяйте каждый параметр после этого амперсандом (&). У Microsoft есть хорошая документация по Graph API.
6. Коды ошибок и обработка ошибок
Иногда HTTP-запросы терпят неудачу, что может ввести пользователя в замешательство. Включите ожидаемые коды ошибок в документацию, чтобы помочь пользователям понять ошибки.
LinkedIn предоставляет стандартные коды ошибок HTTP для обработки ошибок:
7. Примеры фрагментов кода
Фрагменты кода являются неотъемлемой частью вашей документации. Они показывают пользователям, как интегрировать API на разных языках и в разных форматах. Включите в документацию инструкции по установке и интеграции SDK (комплектов для разработки программного обеспечения) на разных языках.
В RapidAPI есть хорошие примеры фрагментов кода для разработчиков:
9. Управление версиями API и журналы изменений
Управление версиями API — неотъемлемая часть дизайна API. Он обеспечивает бесперебойное предоставление услуг вашим пользователям. Управление версиями может улучшить API новыми версиями, не затрагивая клиентские приложения.
Пользователи могут продолжать использовать более старые версии или вовремя перейти на более совершенные. Если есть новые изменения в журналах, включите их в документацию, чтобы пользователи были в курсе.
Microsoft Graph API имеет хорошо задокументированные журналы изменений:
10. Контактная информация для поддержки и обратной связи
Наконец, включите в документацию важные контакты для поддержки и обратной связи. Это гарантирует, что пользователи смогут связаться с вами с отчетами об ошибках и информацией о том, как улучшить API.
Ценность документации API
Если вы создаете API для коммерческой ценности, его успех определяется потреблением. И чтобы пользователи могли использовать ваш API, они должны его понимать.
Документация оживляет API. Он подробно объясняет компоненты простым языком, который продает пользователям их ценность и использование. Пользователи с удовольствием воспользуются вашим API, если у них будет отличный опыт разработки.
Хорошая документация также помогает упростить обслуживание и масштабирование API. Команды, работающие с API, могут использовать документацию для управления им.
