# Джейсон Хармон: «Плохая API-документация — главный риск безопасности»

Источник: https://www.youtube.com/watch?v=0CSyIBHQy9g
Канал: freeCodeCamp.org
Опубликовано: 29.11.2023

---

## Искусство API-документирования: Как создавать платформы, которые любят разработчики
[[JUMP:0:00]]

Хорошая API-документация — это не просто набор технических инструкций, а фундамент успешного продукта, инструмент обеспечения безопасности и ключевой фактор масштабируемости бизнеса. По словам Джейсона Хармона, CTO в Stoplight, документация является «жизненной силой» современной разработки, способной превратить разрозненный набор функций в полноценную платформу. Этот курс, представленный совместно с APPEC University, охватывает всё необходимое для создания документации, которая помогает разработчикам быстро начать работу и дает уверенность бизнес-лидерам.

## 🏗️ Определение API-документации и аудитория
[[JUMP:2:53]]

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

Хармон предлагает правило: «Разработчики пробуют, бизнес покупает». Это означает, что контент должен говорить на двух языках:

1.  **Технический уровень:** Пошаговые инструкции и примеры кода для инженеров, чтобы они могли оценить удобство интеграции.
2.  **Бизнес-уровень:** Описание ценности продукта, его возможностей и надежности для лиц, принимающих решения о бюджете.

Разделение на внутреннюю и внешнюю документацию также критично: если внутренняя часто содержит ссылки на проприетарные данные и операционные метрики, то внешняя требует сильного брендинга, маркетингового посыла и фокусировки на пользовательском опыте.

## 📚 Анатомия эталонной документации
[[JUMP:9:21]]

Эффективная документация API обычно состоит из трех основных компонентов:

*   **Справочные материалы (Reference):** «Энциклопедия» API. Здесь описываются эндпоинты, методы (GET, POST, и т.д.), параметры запросов и структура ответов. Важно, чтобы каждое поле ответа было снабжено точным определением, а не просто названием, которое может быть двусмысленным.
*   **Концепции (Concepts):** Описание бизнес-логики и сценариев использования. Это ответы на вопросы «зачем» и «как это работает в связке с другими API».
*   **Задачи (Tasks):** Workflow-ориентированные руководства, которые показывают, как достичь конкретного результата, например, провести оплату через Stripe.

Одним из важнейших элементов Хармон называет раздел «Начало работы» (Getting Started). Идеальный путь пользователя — совершить успешный API-вызов менее чем за 5 минут. Если для этого требуется несколько способов авторизации, это «красный флаг» для безопасности.

## 🔒 Безопасность и «армия зомби»
[[JUMP:41:35]]

Документирование API — это скрытый метод обеспечения безопасности. 

*   **Риски:** Несогласованные или отсутствующие механизмы авторизации (Broken Object Level Authorization и Broken Authentication) являются основными причинами инцидентов.
*   **Shadow/Zombie API:** Так называют API, о существовании которых никто не знает, а значит, они не обновляются и не мониторятся. Согласно приведенным данным, 94% компаний сталкивались с инцидентами из-за подобных «забытых» активов в течение последнего года.
*   **Audit-as-you-go:** Процесс написания документации выступает как форма QA. Автор документации невольно проводит аудит безопасности, обнаруживая дыры в доступе, которые невозможно логично описать.

## ⚙️ Автоматизация и качество
[[JUMP:61:36]]

Для масштабирования документации Хармон рекомендует отходить от ручного написания в пользу инструментов, которые генерируют её на основе спецификаций, таких как OpenAPI (ранее Swagger).

Рекомендуемые подходы:

1.  **API Style Guides:** Использование правил (например, через Stoplight Spectral) позволяет автоматизировать проверку консистентности: наличие контактов, описаний полей и стандартов форматирования.
2.  **Линтеры для текста:** Инструменты вроде **Vale** помогают соблюдать единый стиль и корпоративные стандарты написания технического текста.
3.  **Интерактивность:** Современный стандарт — наличие кнопки «Try it», позволяющей отправить запрос в «песочнице», и примеры кода на разных языках.

## 🎯 Лучшие практики: итоги
[[JUMP:144:45]]

*   **Избегайте «Булшит-бинго»:** Используйте понятный язык, свободный от корпоративного жаргона, чтобы снизить барьер для входа.
*   **Итеративность:** Документация — это не «написал и забыл». Она должна обновляться вместе с кодом. Устаревшие скриншоты или информация хуже, чем их отсутствие.
*   **Доступность:** Учитывайте потребности 15% мирового населения, нуждающегося в специализированном контенте, например, за счет правильного использования контрастов цветов и меток для скринридеров.