Api документация что это

Удачный шаблон документации на API, который будут читать

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

Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу «чем больше, тем лучше».

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

Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях.

С чего все начинается

Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона?

Самое важное понять, кто и для чего будет пользоваться документацией.

Аналитик думает, что документы нужны всем, а остальные уверены, что им они не нужны. Поэтому для составления удачного шаблона нужно понять, что мотивирует вашу команду прочитать документацию.

Перед нами команда, которая разрабатывает новые интеграции.

Системный аналитик

Отвечает за документацию

Product Owner

Ставит задачи аналитику

Разработчик

Тестировщик

Проверяет, правильно ли сделал разработчик

Задача аналитика — описать интеграцию систем (спроектировать API).

Для чего команде документ

Product owner

В описании ищет ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Разработчик

Без документа не понимает как ему делать задачу, поэтому вопросы у него такие:

Что мне делать: параметры запроса-ответа?
В какие системы сходить за данными или передать?

Тестировщик

Прочитав описание интеграции, сможет ответить на вопросы:

Как бы это все сломать: какие ошибки можно сделать?
Где найти тестовые запрос-ответ?
С какими системами есть взаимодействие, чтобы проверить весь путь?

Аналитик другой команды

Этому человеку нужна любая документация, потому что у него один вопрос:

Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Скорость разработки — это важное преимущество, потому что кто первый вышел на рынок с продуктом, тот и выиграл. Время на написание или чтение ТЗ выделяется мало, поэтому документ должен содержать необходимый и достаточный минимум для быстрой разработки.

Из чего состоит шаблон

В шаблоне на интеграцию (API) будут разделы:

Основная информация Запрос/Ответ Входные параметры Проверки Выходные параметры Положительный ответ Ответ с ошибками Описание интеграции Интеграции Интеграция с сервисом №1

Почему именно такая структура?

Спокойствие, только спокойствие, сейчас все расскажу!

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

Основная информация

В разделе можно найти ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Запрос/Ответ, Входные и выходные параметры

В этих разделах документа есть информация:

Что мне делать: параметры запроса-ответа?
Где найти тестовые запрос-ответ?
Как бы это все сломать: какие ошибки можно сделать?

Описание интеграции

Здесь есть ответы на вопросы:

В какие системы сходить за данными или передать?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Как применить шаблон на практике

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

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

Автор — ФИО, кто пишет или правит документ
Задача — ссылка на задачу (например, JIRA) или описание задачи
Бизнес постановка — описание какую пользу приносит эта задача пользователям
Связанные документы — документы или ссылки с описанием, что в них находится

История изменений документа

Раздел содержит таблицу:

Версия — номер версии
Дата — дата в формате ДД.ММ.ГГГ
Автор — ФИО кто создал или изменил документ
Описание изменений — текстовое описание того, что вы добавили в документ.

Запрос/Ответ

Пример запроса и ответа для добавления информации о животном на сайте

Входные параметры

Раздел содержит таблицу:

Параметр — название параметра на английском
Тип данных — указать тип данных параметра с ограничениями по длине если они есть
Обязательность — да/нет
Описание — понятное описание для чего используется параметр
Варианты значений — перечислить варианты значений с пояснениями, для чего они используются или привести пример одного из значений

Проверки

Раздел содержит таблицу:

Параметр — название параметра на английском
Проверка — условие и результат проверки

Выходные параметры

Положительный ответ

Параметры аналогичны входным

Ответ с ошибками

Описание интеграции

Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/

Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок 🙂

Интеграции

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

Например, если бы метод POST /pet пошел бы в следующую систему для сохранения информации о животном.

Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке

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

Возможно вам шаблон не подойдет, но вы всегда можете составить свой и поделиться им в комментариях.

[API как продукт] Документация

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

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

1. Необходимо установить (чем быстрее, тем лучше!) подходит ли в принципе данный сервис для вашего проекта.
2. Если да, то нужно найти, как с его помощью решить конкретную задачу.

Фактически, новички (т.е. те разработчики, которые не знакомы с вашим API), как правило, хотят ровно одного: скомпоновать из имеющихся примеров код, решающий их конкретную задачу, и больше никогда к этому не возвращаться. Звучит, конечно, не очень-то привлекательно с точки зрения усилий и времени, которые вы затратили на разработку API и документации к нему, но суровая реальность выглядит именно так. Кстати, поэтому же разработчики всегда будут недовольны качеством вашей документации — поскольку решительно невозможно предусмотреть все возможные варианты, какие комбинации каких примеров нужны новичкам, и какие конкретно термины и концепции в примере окажутся им непонятны. Добавим к вышесказанному то соображение, что не-новичкам, то есть разработчикам, уже знакомым с системой и ищущим решения каких-то сложных специфических кейсов, как раз совершенно бесполезны комбинации простых примеров, и им, ровно наоборот, нужны подробные материалы по продвинутой функциональности API.

Вводные замечания

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

Однако следует учесть, что документация будет использоваться также и для поиска по ней — таким образом, каждая страница должна содержать достаточные наборы ключевых слов, чтобы находиться в поиске. Это несколько противоречит требованию лаконичности и компактности, но таков путь.

Виды справочных материалов

Спецификация / справочник / референс

Любая документация начинается с максимально формального описания доступной функциональности. Да, этот вид документации будет максимально бесполезен с точки зрения удобства использования, но не предоставлять его нельзя — справочник является гигиеническим минимумом. Если у вас нет документа, в котором описаны все методы, параметры и настройки, типы всех переменных и их допустимые значения, зафиксированы все опции и поведения — это не API, а просто какая-то самодеятельность.

Сегодня также стало стандартом предоставлять референс в машиночитаемом виде — согласно какому-либо стандарту, например, OpenAPI.

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

Важно: формальная спецификация не является документацией сама по себе; документация — это слова, которые вы напишете в поле description для каждого поля и метода. Без словесных описаний спецификация годится разве что для проверки, достаточно ли хорошо вы назвали сущности, чтобы разработчик мог догадаться об их смысле самостоятельно.

В последнее время часто описания номенклатуры методов выкладываются также в виде готовых коллекций запросов или фрагментов кода — в частности, для Postman или аналогичных инструментов.

Примеры кода

Исходя из вышесказанного, примеры кода — самый важный инструмент привлечения и поддержки новых пользователей вашего API. Исключительно важно подобрать примеры так, чтобы они облегчали новичкам работу с API; неправильно выстроенные примеры только ухудшат качество вашей документации. При составлении примеров следует руководствоваться следующими принципами:

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

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

Песочницы

Примеры станут намного полезнее для разработчиков, если будут представлены в виде «живого» кода, который можно модифицировать и запустить на исполнение. В случае библиотечных API это может быть просто онлайн-песочница с заранее заготовленными примерами (в качестве такой песочницы можно использовать и существующие онлайн-сервисы типа JSFiddle); в случае других API разработка песочницы может оказаться сложнее:

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

Руководство (туториал)

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

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

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

Как правило, руководство представляет собой общий блок (основные термины и понятия, используемые обозначения) и набор блоков по каждому роду функциональности, предоставляемой через API.

Часто в составе руководства выделяется т.н. ‘quick start’ (‘Hello, world!’): максимально короткий пример, позволяющий новичку собрать хотя бы какое-то минимальное приложение поверх API. Целей его существования две:

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

Quick start-ы также являются отличным индикатором того, насколько хорошо вы справились с определением частотных кейсов и разработкой хелперных методов. Если ваш quick start содержит более десятка строк кода, вы точно что-то делаете не так.

Часто задаваемые вопросы и база знаний

После того, как вы опубликуете API и начнёте поддерживать пользователей (см. предыдущую главу), у вас также появится понимание наиболее частых вопросов пользователей. Если интегрировать ответы на эти вопросы в документацию так просто не получается, имеет смысл завести отдельный раздел с часто задаваемыми вопросами (ЧаВо, англ. FAQ). Раздел ЧаВо должен отвечать следующим критериям:

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

  Кроме того, раздел ЧаВо очень хорошо подходит для того, чтобы явно донести главные преимущества вашего API. В виде пары вопрос-ответ можно наглядно рассказать о том, как ваш API решает сложные проблемы красиво и удобно (или хотя бы решает вообще, в отличие от API конкурентов).

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

  Офлайн-документация

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

  Проблемы дублирования контента

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

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

  Если вы поддерживаете обратную совместимость, то можно попытаться поддерживать единую документацию для всех версий API. В этом случае для каждой сущности нужно указывать, начиная с какой версии API появилась её поддержка. Здесь, однако, возникает проблема с тем, что получить документацию для какой-то конкретной (устаревшей) версии API (и вообще понять, какие возможности предоставляла определённая версия API) крайне затруднительно. (Но с этим может помочь офлайн-документация, о чём мы упоминали выше.)

  Проблема осложняется, если вы поддерживаете документацию не только для разных версий API, но и для разных сред / платформ / языков программирования — скажем, ваша визуальная библиотека поддерживает и Android, и iOS. В этой ситуации обе версии документации полностью равноправны, и выделить одну из них в ущерб другой невозможно.

  В этом случае необходимо выбрать одну из двух стратегий:

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

  Качество документации

  Важно отметить, что документация получается максимально удобной и полезной, если вы рассматриваете её саму как один из продуктов в линейке сервисов API — а значит, анализируете поведение пользователей (в том числе автоматизированными средствами), собираете и обрабатываете обратную связь, ставите KPI и работаете над их улучшением.

  Документация 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) означает репрезентативную передачу состояния.

  

  Более подробно о принципах 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 и стратегиях их документирования. Вы можете оставаться в курсе об этих сообщениях, подписавшись на его бесплатную рассылку.

  Документирование API

  

  При фразе «Документирование API» многие приходят в ужас, так как, на первый взгляд, это кажется очень трудным, страшным и тяжёлым. Документ по ГОСТу сразу кажется небольшой детской сказкой на этом фоне. Но не так страшен чёрт, как его малюют! Я не говорю, что документирование API — это легко и просто. Да этому нельзя научиться из одной короткой статьи или видео, но если придёт понимание этой темы, то и на изучение этой темы уйдёт гораздо меньше времени. Да–к, что же такое API? И как его задокументировать? В данной статье рассмотрена эта очень непростая тема.

  Что такое API?

  API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант, предоставляемые самим приложением или операционной системой для взаимодействия с внешними программами.
  Например, у вас есть кот Барсик, который любит лежать на обеденном столе. Вам это не нравится. Вы говорите Барсику: «Барсик, брысь со стола!». Барсик хоть и нехотя, но слезает со стола. Так вот, API — это набор команд, благодаря которым кот Барсик понял хозяина, что ему следует слезь со стола. Другой пример, если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API — это множество «ручек», которые доступны пользователю данного ящика и которые он может вертеть и дёргать.
  При этом пользователю необязательно понимать и знать, что такое API. API это «язык» общения между двумя программами и необходим программистам. API создаётся чтобы приложения созданные разными разработчикам корректно существовали вместе и могли взаимодействовать друг с другом. Компоненты образуют иерархию, в результате которой высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов. По такому принципу построены протоколы передачи данных по Интернет. Каждый уровень пользуется функциональностью предыдущего («нижележащего») уровня и, в свою очередь, предоставляет нужную функциональность следующему («вышележащему») уровню.
  На рисунке ниже представлена схема СЭД «Кодекс: Документооборот», в которой отображено API для внешних систем, а также для внутренних в данной СЭД.

  

  API библиотеки функций и классов включает в себя описание сигнатур и семантики функций.

  Сигнатура функции

  Сигнатура функции — это часть общего объявления функции, позволяющая средствам трансляции идентифицировать функцию среди других. В различных языках программирования существуют разные представления о сигнатуре функции, что также тесно связано с возможностями перегрузки функций в этих языках.
  Например, в языке программирования C++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет участвовать и имя класса.
  В языке программирования Java сигнатуру метода составляет его имя и последовательность типов параметров; тип возвращаемого значения в сигнатуре не участвует.
  В СЭД «Кодекс: Документооборот» используется API на основе web-технологий REST-API, на её примере рассмотрим формирование вызова любого GET\POST запроса.

  Пример формирования вызова любого GET\POST запроса

  //на вход принимаются url запроса, метод (GET/POST), токен, и объект, который необходимо //передать, если это POST public static byte[ ] CreateRequest(string url, string method, string token, Object obj)  HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); request.Method = method; //Помещаем токен в заголовок request.Headers.Add(«Token», token); // Если POST – записываем передаваемый объект if (request.Method == «POST»)  UTF8Encoding encoding = new UTF8Encoding(); string jsonString = JsonConvert.SerializeObject(obj); var bytes = encoding.GetBytes(jsonString); request.ContentType = «application/json»; request.ContentLength = bytes.Length; using (var newStream = request.GetRequestStream())  newStream.Write(bytes, 0, bytes.Length); newStream.Close(); > > try  //Получаем ответ от сервиса HttpWebResponse httpWResponse = (HttpWebResponse)request.GetResponse(); using (MemoryStream mstr = new MemoryStream())  httpWResponse.GetResponseStream().CopyTo(mstr); //возвращаем полученный с сервиса объект в виде массива байт return mstr.ToArray(); > > catch (WebException ex)  //обрабатываем исключения var stCode = ((HttpWebResponse)ex.Response).StatusCode; > return null; >

  Семантика функции

  Семантика функции — это описание того, что данная функция делает. Семантика функции включает в себя описание того, что является результатом вычисления функции, как и отчего этот результат зависит. Обычно результат выполнения зависит только от значений аргументов функции, но в некоторых модулях есть понятие состояния. Полным описанием семантики функций является исполняемый код функции или математическое определение функции.
  Ниже, для примера, рассмотрена одна из функций СЭД «Кодекс: Документооборот».

  /Documents/GetDocLinkedObjects GET
  Возвращает список связанных документов по переданному идентификатору.

  Таблица 1 — Идентификатор документа

  Параметр	Тип	Описание
  uid	Guid	Идентификатор документа

  Возвращаемое значение – список связей с документом.

  Таблица 2 — Список связей с документом

  Свойство	Тип	Описание
  DocUID	Guid	Идентификатор связанного элемента
  DirectionType	DirectionType	Тип связанности (тип подчинения)
  LinkType	Integer	Идентификатор типа связи (из справочника LINK_TYPES)
  LinkTypeName	String	Наименование типа связи
  OperatorUID	Guid	Идентификатор автора, создавшего связь

  Проблема документирования API

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

  1. Сложность написания документации API, так как это очень трудная тема. Неясно как писать, что писать и прочее. При написании возникает очень много вопросов. Тем более, если человек до этого никогда не имел дело с документированием API.
  2. Поддержка документации API в актуальном состоянии.

  Проблема стандартизации API

  В первую очередь с документацией API будут работать люди. В связи с этим, для общего понимания нужен некий стандарт разработки API, чтобы разработчики даже при беглом ознакомлении понимали, как с ним корректно взаимодействовать. Также наличие стандарта API позволяет использовать средства автоматической кодогенерации, что существенно повышает скорость разработки, но об этом я расскажу позже.
  Подобного рода внутренний стандарт лучше разработать и утвердить с отделом разработки программного обеспечения.
  Для примера документация API должна включать:

  1. Пример полного запроса.
  2. Примеры ожидаемого ответа.
  3. Список кодов ошибок.
  4. Удобный для поиска Web–интерфейс.
  5. Предупреждения об изменении версии и расписание устаревания.

  Способы создания документации API

  1. Создать текстовый документ.
     Это, конечно, самый простой вариант, в котором можно сделать максимально подборные описания, но такой документ сложно поддерживать в актуальном состоянии, на его создание уйдёт куча времени, да и использовать его в других сферах (например, тестирование) нельзя.
  2. Создать документацию с помощью специализированных программ (спецификаций).
     Их нельзя сделать такими подробными, как тестовый документ, но зато можно настроить автогенерацию (изменение кода приложения документации автоматически с учётом изменений), которая позволит быть документации API всегда в актуальном состоянии, что очень важно. Поэтому сейчас большинство компаний выбирает именно этот способ. Повторюсь, ведь от актуальности документации API зависит качество разработки ПО.

  Одни из самых популярных спецификаций — это RAML, Swagger и API Blueprint.
  Например, если программирование Системы происходи в MS Visual Studio, то в ней автоматически генерируется Xml (представлена на картинке ниже), с помощью которой уже можно создать в любой другой спецификации документацию API.

  

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

  Swagger

  Для учебных целей можно открыть Swagger Editor, в котором можно попробовать создавать документацию API.
  Сайт: http://editor.swagger.io/
  Swagger Editor состоит из двух блоков: код (слева), документация API (блок справа (зависит от блока слева)).

  

  Код

  Типы аннотаций, использованные для описания методов:

  • Get — означает, что для доступа к методу должен использоваться http-метод GET. Существуют аналогичные аннотации для всех http-методов: Post, Put и другие.
  • Parameter — используется для описания параметров метода.
  • Response — используется для описания ответа API.
  • Schema — используется для описания формата выходных данных.

  

  Документация API

  В Swagger генерация происходит автоматически.
  Полученная документация содержит описание всех типов данных, возвращаемых API, список доступных методов c подробным описанием.

  

  Описание метода API содержит его url, описание всех параметров, а также все варианты ответов. Т.к. мы ссылались на модель Post в описании ответа, мы можем видеть ссылку на эту модель и даже пример ответа API, сгенерированный на основании описания модели.

  В заключении хотелось бы сказать, что документированию API невозможно научиться по одной статье, тут нужна куда более сильная теории и много практики. У вас обязательно должен быть человек, который вам поможет, подскажет и укажет на ваши ошибки. Но не забывайте, что документирование API невозможно без взаимодействия с Отделом разработки ПО. Они помогут установить и настроить программу, подскажут, где и что взять, где и что посмотреть.

  Похожие публикации:

  1. User config что это
  2. Vendor lock что это
  3. Как удалить linux mint
  4. Работа инхаус что это