До этого момента мы в основном фокусировались на справочных аспектах документации API (конечные точки). Адресная документация - это только один аспект документации API. В этом разделе поговорим о концептуальных разделах, которые обычно встречаются в документации API. Вместо понятия «концептуальные разделы» можно принимать эту информацию в качестве «руководства пользователя».
Разделы руководства пользователя
Ниже приведены концептуальные разделы, обычно встречающиеся в документации API:
- Обзор API
- Начало работы
- Требования аутентификации и авторизации
- Коды статусов и ошибок
- Ограничения скорости
- Описание и примеры кода
- SDK и пример приложений
- Краткое справочное руководство
- API Глоссарий
- Лучшие практики API
Помимо этих разделов, можно добавлять и другие задачи и пособия, относящиеся к API, исходя из того, что ожидается от пользователей, и бизнес-сценариев, для которых они будут использовать API.
В каждом безадресном разделе будут приведены общие описания и обзоры содержания этих разделов, а также примеры с реальных сайтов документации API.
В своем найденном опен-сорс проекте можно пройти по каждому концептуальному разделу и оценить его. Хотя многие из понятий в разделе являются базовыми, при рассмотрении информации в контексте, то есть, как на самом деле реализована информация, все становится намного интереснее.