Edit me

Документация API: руководство для технических писателей

На этом курсе по разработке документации API не будем вести речь об абстрактных понятиях, лучше подойдем практически к документированию API: изучим документацию API на примере использования различных API сервисов прогнозов погоды.

Используя API на этом курсе, мы узнаем что такое “конечная точка” или эндпоинт, какие у нее могут быть параметры, типы данных, что такое аутентификации, curl, JSON, поближе познакомимся с командной строкой, консолью разработчика Chrome, JavaScript и многими другими деталями, связанных с REST API.

Идея курса: посмотреть на реальные сценарии использования API, сделав этот курс эффективным. Изучать концепты API независимо от контекста мы не будем.

На курсе мы изучим стандарты, инструменты и спецификации REST API. Узнаем о необходимых разделах в документации API, проанализируем примеры документации REST API от различных компаний, узнаем, как присоединиться к проекту с открытым исходным кодом, для получения опыта, и многое другое.

Будет интересно!

О REST API

Вкратце, REST API (которые является разновидностью веб-API) используют запросы и ответы, что мало чем отличается от посещения веб-страницы. Вы делаете запрос к ресурсу, хранящемуся на сервере, и сервер отвечает запрошенной информацией. Протокол, используемый для передачи данных - HTTP. «REST» (Representational State Transfer) означает репрезентативную передачу состояния.

request
REST API используют запросы и ответы по протоколу HTTP

Более подробно о принципах REST в разделе Что такое REST API?. В документации API описываются различные конечные точки, их методы, параметры и другие сведения, а также документируются образцы ответов от конечных точек.

От практики до документации

После изучения модуля “Используем API как разработчики”, откроются новые горизонты и простой технический писатель станет техническим писателем, которому может документировать конечные точки API.

Как технические писатели, будем рассматривать каждый элемент в документации API:

  1. Описание ресурса
  2. Конечная точка и методы
  3. Параметры
  4. Пример запроса
  5. Пример ответа

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

Наконец, изучим разные способы публикации API документации, изучим инструменты и спецификации, такие как GitHub, Jekyll и подход Docs-as-code. Узнаем, как использовать шаблоны, создавать интерактивные консоли API, чтобы пользователи могли сделать запросы и посмотреть ответы, а также узнаем, как управлять своим контентом с помощью контроля версий.

Мы также окунемся в спецификации, такие как спецификация OpenAPI и Swagger, который предоставляют инструментарий для спецификации OpenAPI. Кроме того, узнаем, как документировать нативные библиотеки API и генерировать Javadoc. Вместе с концепциями будут продемонстрированы реальные примеры.

Для кого этот курс

Курс в первую очередь нужен следующим специалистам:

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

Организация курса

  1. Введение в REST API
    • API-интерфейсы REST очень популярны в мире IT, и веб превращается в совокупность взаимосвязанных API-интерфейсов. REST API состоят из запросов и ответов от сервера. Технические писатели способные писать документацию для разработчиков имеют огромные перспективы. Этот курс поможет разобраться с документированием API, особенно при помощи практических занятий.
  2. Используем REST API как разработчики
    • Роль разработчика поможет лучше понять потребности разработчиков, а также то, что разработчики обычно ищут в документации API. Разработчики часто используют такие инструменты, как Postman или curl, для совершения запросов. Они смотрят на структуру ответа и динамически интегрируют необходимую информацию в веб-страницы и другие приложения.
  3. Документирование конечных точек API
    • Документация конечных точек API состоит из пяти основных разделов: описания ресурсов, конечные точки и методы, параметры, примеры запросов, примеры ответов и схемы. Чтобы задокументировать конечные точки API, старайтесь предоставлять подробную информацию для каждого из этих разделов.
  4. Спецификация OpenAPI и Swagger
    • Спецификация OpenAPI предоставляет один из способов описания REST API и включает все разделы, упомянутые в модуле Документирование конечных точек API. Фреймворки, такие как Swagger UI, могут анализировать спецификацию OpenAPI и генерировать интерактивную документацию, которая позволяет пользователям опробовать конечные точки при изучении API.
  5. Тестирование документации API
    • Тестирование документации имеет решающее значение для предоставления точной, полной информации. Из-за высокого уровня сложности и технических требований документации API и иной документации разработчиков многие технические писатели склонны брать информацию из такой документации и добавлять ее без личного тестирования. Однако простая игра в редакционную/издательскую функцию может сделать из вас простого секретаря.
  6. Концептуальные разделы API
    • В то время как адресные темы в API, как правило, получают наибольшее внимание, концептуальные разделы, такие как разделы о начале работы, информация об авторизации, возможных лимитах скорости, кодах состояния и ошибок, кратких справочных руководствах и других темах, составляют около половины документации. Этими вопросами обычно занимаются технические писатели, а не разработчики. Вы можете оценить качество документации API, посмотрев, включает ли она эти не справочные темы.
  7. Публикация документации API
    • Документация по API часто соответствует принципу docs-as-code, где инструменты для создания и публикации документации тесно связаны с теми же инструментами, которые разработчики используют для написания, управления, построения и развертывания кода. Docs-as-code включает в себя использование облегченных форматов разметки, таких как Markdown, совместную работу с помощью Git или других систем управления версиями, создание сайта документации с помощью генератора статического сайта и развертывание его с помощью модели непрерывной сборки, где сборка происходит на сервере при фиксировании изменений в определенной ветви.
  8. Работа технического писателя API
    • Чтобы получить работу, имеющую отношение к документации API, нужно продемонстрировать портфолио и технические способности. В портфолио должны быть включены образцы документации, написанной для разработчиков. Одним из способов создания такого портфолио является работа над проектом с открытым исходным кодом. Постоянное развитие мира документации для разработчиков потребует постоянного изучения больших объемов кода, несмотря на свою сложность.
  9. Нативные библиотеки API
    • API нативных библиотек относятся к Java, C ++ или другим API, специфичным для программирования. При таком подходе вместо запроса информации через Интернет, библиотека кода загружается и интегрируется в проект. Библиотека компилируется непосредственно в сборку приложения (а не доступна через веб-протоколы, как с REST API). Хотя такой тип API встречается реже, он включен здесь частично, для пояснения, что отличает API REST от API нативных библиотек.
  10. Глоссарий и источники
    • Документация API полна жаргонов, сокращений и множества новых терминов. Этот глоссарий предоставляет список терминов и определений. Кроме того, этот модуль содержит дополнительные упражнения и информацию, например, дополнительные действия по вызову API или дополнительную информацию об альтернативных спецификациях.

Последовательность и действия

Необязательно изучать модули по порядку - можно “гулять” по ним по своему усмотрению. Но некоторые из модулей (например, Используем REST API в роли разработчика и Конечные точки API) желательно пройти последовательно.

Кроме основной цели курса - помочь в обучении, существует множество видов деятельности, которые требуют практического программирования и других упражнений. Наряду с учебной деятельностью существуют также концептуальные глубокие погружения, но основное внимание всегда уделяется обучению на практике.

Практические занятия помечаются иконкой в заголовке раздела: 👨‍💻

Упражнения интегрированы в модули, но можно увидеть список заданий в «Практических занятиях».

Курс назван «курсом», а не книгой или веб-сайтом, главным образом потому, что в каждом модуле включены практические занятия для наработки опыта.

Поможет ли курс получить работу техписателя API?

Самая распространенная причина, по которой люди проходят этот курс - непонимание процесса документирования API. Курс поможет осуществить задуманное, но только пассивное чтение разделов не поспособствует этому. Необходимо выполнять упражнения, в каждом модуле, особенно те, которые связаны с работой над контентом из опен-сорс проекта. Такие практики имеют решающее значение для накопления опыта и пополнения портфолио. Более подробные сведения приведены в модуле Работа технического писателя API.

Навыки программирования не требуются

Что касается необходимого технического бэкграунда для прохождения курса, какие-либо знания специфических языков программирования не нужны, но зная базу HTML, CSS и JavaScript будет немного легче.

Этот курс рассчитан для новичков. Если есть понимание концепции программирования, можно пропускать некоторые разделы и переходить к темам, которые хотите узнать больше.

Некоторые примеры кода в этом курсе используют JavaScript. JavaScript может быть языком, который фактически используется при документировании REST API, но могут быть и другие языки или платформы программирования, которые тоже важно знать.

JavaScript - один из самых полезных и простых языков для изучения, поэтому его проще использовать в примерах кода для данного введения в документацию по REST API. JavaScript позволит тестировать код, просто открывая его в браузере (а не компилируя в IDE). (Быстрый ускоренный курс по JavaScript).

Инструменты для работы

  • Текстовый редактор (Atom или Sublime text);
  • браузер Chrome с его встроенной консолью Javascript, которая хорошо подходит для проверки JSON. Firefox тоже подойдет;
  • Postman - приложение, которое позволяет вам делать запросы и видеть ответы через GUI-клиент;
  • curl необходим для выполнения запросов к конечным точкам из командной строки. На компьютерах Mac уже установлен curl. Пользователи Windows должны следовать инструкциям по установке curl здесь. (Примечание: выбирайте одну из «бесплатных» версий для установки curl.);
  • Git - инструмент контроля версий, который разработчики часто используют для совместной работы над кодом. Для Windows здесь описана установка и настройки Git и эмулятора терминала Git BASH. Для Mac смотрите Загрузка Git, можно рассмотреть возможность установки iTerm2;
  • аккаунт на GitHub будет использоваться для различных действий, иногда для демонстрации рабочего процесса Git, а иногда в качестве службы аутентификации для инструментов разработчика. Если еще нет учетной записи GitHub, самое время ее создать;
  • аккаунт StopLight, сервиса, который предоставляет инструменты визуального моделирования для работы со спецификацией OpenAPI. Создать учетную запись Stoplight можно, используя свои учетные данные GitHub;
  • ключ к API OpenWeatherMap. Мы будем использовать API OpenWeatherMap для некоторых упражнений. Для активации ключа API OpenWeatherMap требуется несколько часов, поэтому лучше получить ключ API заранее - тогда, когда вы приступите к действиям API OpenWeatherMap, все будет готово. Чтобы получить свой (бесплатный) ключ API OpenWeatherMap, перейдите по адресу https://openweathermap.org/. Нажмите Зарегистрироваться в верхней панели навигации и создайте учетную запись. После того, как вы зарегистрируетесь, войдите в систему и найдите ключ API по умолчанию на панели инструментов разработчика. Он находится на вкладке API Keys. Скопируйте ключ в то место, где его легко найти.

Видео записи

Видео записи курса здесь.

Подборка предстоящих презентаций в блоге автора курса для получения подробной информации о будущих семинарах и презентациях.

Презентации курса

Есть различные презентации, охватывающие различные модули этого курса, которые можно использовать при подготовке и проведения семинаров. Преподаватель, адаптирующий этот материал для курса по документации API в программе технической коммуникации, может клонировать и изменять слайды. Слайды курса здесь.

Слайды используют RevealJS, который представляет собой HTML / CSS / JS-фреймворк для слайдов.

Актуальность контента курса

Одной из проблем любого технического курса является обеспечение актуальности контента. Технологии быстро меняются, и благодаря многим практическим занятиям в этом курсе, некоторые шаги легко устаревают с течением времени. Автор курса пытается сохранить здоровый баланс между общими и конкретными деталями в содержании курса. Если вы обнаружите, что что-то устарело, или найдены ошибки, pull requests are welcome.

Оставаться в курсе

Если вы проходите этот курс, скорее всего, захотите узнать больше об API. Автор публикует регулярные статьи, в которых рассказывается об API и стратегиях их документирования. Вы можете оставаться в курсе об этих сообщениях, подписавшись на его бесплатную рассылку.

🔙

Go next ➡