Разработка описания API

Термин API на слуху у большинства пользователей digital-сферы. Данная аббревиатура расшифровывается как Application Programming Interface. API представляет собой набор способов и правил, по которым происходит обмен информацией между несколькими программами.

 

Как эффективно использовать API? На этот вопрос ответит API-документация. В ней содержится информация, необходимая для работы с API и подробные сведения о функциях и типах возвращаемых значений.
Документация API должна быть актуальна и структурирована. Условно в ее структуре можно выделить два смысловых блока: справочная информация и руководство пользователя.

В блоке со справочной информацией встречаются следующие разделы:

• описание ресурсов (информация, возвращаемая API);
• конечные точки и методы (конечные точки указывают, как получить доступ к ресурсу, а методы указывают на допустимые взаимодействия с ресурсом – GET, POST, DELETE);
• параметры (информация для передачи конечной точке, которая может повлиять на ответ);
• примеры запросов (пример применения конечной точки, указывающий на определенные настроенные параметры);
• примеры ответов (пример ответа на пример запроса).

В руководство пользователя могут быть включены разделы:

• обзор API (информация о назначении API);
• начало работы (описание первых шагов пользователя);
• требования аутентификации и авторизации (методы авторизации и информация об ошибках при неверной аутентификации);
• коды ошибок и статусы (число в заголовке ответа, которое указывает на общую классификацию ответа);
• ограничение скорости (определение, насколько часто можно осуществлять запросы по конкретной конечной точке);
• SDK и пример приложений (может включать коллекцию файлов, работающих вместе, или примеры приложений);
• краткое справочное руководство (информация о системе в целом при помощи списка конечных точек API);
• глоссарий (список уникальных терминов);
• оптимальные методики (советы для разработчиков по работе с API).

Существует три основных подхода к написанию документации API:

• пишем код, а потом документ;
• описываем документ, а на его основе пишем код;
• пишем параллельно код и документ.

К первому подходу прибегают, когда проект уже готов и не требует изменений. В данном случае документация воспринимается как формальность. Она создается для специалистов, которые в будущем будут к ней обращаться.
Второй подход применим на старте проекта. В данном случае собирается коллегия из всех заинтересованных сторон (backend, frontend и др). На основе подобного обсуждения формируются четкие требования к будущему проекту.
В процессе создания крупного развивающегося проекта прибегают к третьему подходу. Требования к API могут меняться по мере разработки проекта: что-то потребуется убрать, добавить или скорректировать.
Документации API зачастую разрабатывается с использованием подхода docs-as-code. На облегченном языке разметки создается текст документа, который хранится в репозитории Git. Сбор документации в разные форматы происходит с помощью генератора статических сайтов.

Описание API может быть создано как вручную, так и при помощи специальных инструментов, которые позволяют автоматизировать процесс создания и обновления документации. К подобным инструментам относятся Postman, DapperDox, SwaggerHub, Slate, ReadMe и др.
Чаще всего написанием документации API занимается разработчик ПО, т.к. он принимает непосредственное участие в создании API. Разработчики пишут документацию исключительно с технической точки зрения. При таком подходе документация нередко выходит непонятной и сложной. Выходом из данной ситуации будет привлечение к разработке документации технического писателя. Чтобы документ был наиболее эффективным, техническому писателю необходимо понимать специфику описываемого API и его функций.