Прежде чем углубимся в технические аспекты API давайте посмотрим на предложения на рынке, на глобальную экосистему и тренды в API документации.
Различные типы API
Мир API широк и разнообразен. Этот курс посвящен API REST, но существует также много других типов API. Бывает, люди начинают просматривать GitHub в поисках проектов API, или когда просматривают различные API в своей собственной компании, они удивляются, что API выглядят незнакомыми по сравнению с API, описанным в этом курсе. Да, есть много типов API, с которыми мы можем встретиться.
Один из способов сортировки различных типов API-интерфейсов состоит в том, чтобы классифицировать их по двум основным группам:
- API-интерфейсы веб-сервисов;
- API веб-сервисов отправляют и получают сообщения через Интернет, используя HTTP для передачи запроса и ответа;
- API веб-сервисов не зависят от языка;
- API-интерфейсы собственных библиотек;
- API-интерфейсы нативных библиотек, включают в себя добавление кода непосредственно в проект для желаемой функциональности;
- API нативной библиотеки зависят от языка.
Ниже собраны самые распространенные типы API:
- API нативных библиотек: API-интерфейсы нативных библиотек, также называемые «API-интерфейсами на основе библиотек», относятся к библиотекам кода (например, JAR-файлам), которые разработчики добавляют непосредственно в свои проекты для обеспечения дополнительной функциональности с помощью классов или других функций, которые можно вызывать локально. Эти API специфичны для языка программирования - например, Java, C ++, Python, Ruby, .NET и так далее. При использовании нативных библиотечных API-функций они (функции) включаются локально в код для расширения операций, которые можно выполнять в своем проекте, обычно без необходимости доступа к ресурсам в сети. API нативных библиотек требуют знания языка программирования, и, как правило, являются наиболее сложным типом API для документирования для технических писателей. См. Обзор нативных библиотек API на этом курсе для получения дополнительной информации о API-интерфейсах Java.
- SOAP APIs: SOAP (Simple Object Access Protocol) API - это веб-сервисы, использующие строгий протокол XML для определения формата обмена сообщениями для запросов и ответов. SOAP характерен для финансовых API и регулируемых отраслей, хотя в значительной степени его заменили на REST. Как стандартизированный протокол, формат сообщения SOAP XML обычно определяется через файл WSDL (язык описания веб-служб), в котором указываются разрешенные элементы и атрибуты при обмене сообщениями. Файл WSDL является машиночитаемым и используется серверами, взаимодействующими друг с другом для облегчения связи. См. SOAP. Более подробная информация о SOAP также представлена в разделе Что такое REST API?
- RPC-based API: RPС (Remote Procedure Call).API на основе RPC - это веб-сервисы, которые вызывают метод на удаленном сервере, доставляя закодированное сообщение через HTTP. Формат зашифрованного сообщения может быть XML для API-интерфейсов XML-RPC или JSON для API-интерфейсов JSON-RPC, но в обоих случаях сообщение, как и другие веб-службы, отправляется на удаленный сервер через HTTP. Методы на удаленных серверах могут быть на любом языке. Например, API-интерфейс XML-RPC может вызывать метод Java, Python или C ++.
- gRPC API: API gRPC - это веб-службы, аналогичные API на основе RPC, в которых веб-служба вызывает функцию или выполняет процедуру на удаленном сервере; однако gRPC использует буферы протокола (указанные в файлах .proto), а не XML или JSON в качестве формата обмена сообщениями. Буфер протокола позволяет определять структуру данных и способ преобразования (сериализации) данных, которые будут использованы принимающим сервером. Буферы протокола легче и эффективнее, чем XML. API gRPC были разработаны Google и опубликованы как платформа с открытым исходным кодом. Посмотрите документацию API gRPC.
- REST API: REST (Representational State Transfer) - это веб-сервисы, которые позволяют отправлять запросы к ресурсам по URL-путям. Указывается операция, которую необходимо выполнить, с помощью пути (например, GET, CREATE, DELETE). Как и в случае с другими API веб-служб, запросы и ответы передаются через HTTP через Интернет, и серверы, принимающие запросы, не зависят от языка запроса (необязательно, чтобы он был определенным языком программирования). Ответы обычно возвращаются в формате JSON или XML. API REST имеют много разных путей (конечных точек) с различными параметрами, которые можно настраивать для определения желаемых результатов. Этот курс в основном посвящен API REST. Подробнее о REST API в разделе Что такое REST API?.
- GraphQL API: GraphQL API - это веб-сервисы, разработанные Facebook, которые позволяют пользователям динамически запрашивать результаты, которые им нужны, по одному пути (конечной точке). GraphQL устраняет необходимость в нескольких URL-запросах или другой пост-фильтрации возвращаемых результатов, для получения нужного результата. Запрос извлекает только необходимые данные, что позволяет сделать запрос и ответ быстрым и конкретным. Страница graphql.org для изучения. Можно еще почитать статью If I am learning to write developer documentation, should GraphQL be on my radar?.
- API голосовых помощников: Такие API использует, например, Alexa. Эти API создаются в облаке и вызывают конечную точку на основе обработки голосовых команд на языке пользователей. Это тот случай, когда API работают за кулисами в облаке, и разработчики создают код (такой как лямбда-функция - облачные вычисления), который обрабатывает входящие запросы, отправленные из API голосового помощника.
- API интернета вещей: API интернета вещей используются физическими устройствами (например датчики или носимые устройства), которые передают или получают данные для подключения устройства к онлайн-сети. Например, датчик термостата в комнате может передавать температуру на центральный контроллер (например, с помощью Nest) через IoT API. Почитать можно здесь App nirvana: Когда Интернет вещей встречает экономику API. И еще API в мире IoT.
Для дополнительной информации можно изучить Типы API Сары Мэддокс. Сара отмечает, что есть также аппаратные API, API-интерфейсы удаленного взаимодействия с объектами, API-интерфейсы веб-сокетов, функции и процедуры ОС и многое другое.
Несмотря на разнообразие API, определяющей характеристикой почти всей документации для разработчиков является то, что она включает документирование какого-то типа API. Вот почему «документация по API» и «документация для разработчиков» используются как синонимы. API облегчают жизнь разработчикам (которые используют API), потому что API выполняют функции или другие задачи более эффективными способами.
Большинство компаний предоставляют информацию и услуги через API-интерфейсы, чтобы помочь третьим сторонам интегрировать информацию или услуги своей компании. В этом и заключается вся идея информационной экономики. Кроме того, многие API доступны только внутри компании, чтобы помочь разработчикам в одной и той же компании внедрять различные сервисы. Например, команда, обрабатывающая операции контроллера платежей, может предоставить API, который другая команда, разрабатывающая приложение компании, может реализовать для обработки платежных транзакций.
Самый распространенный тип API
Просматривая API, многие интересуются, какой тип API наиболее распространен? На какие типы API стоит обратить внимание? Среди API веб-сервисов в отчете о состоянии API на 2019 от компании Smartbear было опрошено более 3000 специалистов по технологиям, и было установлено, что REST-OAS / Swagger был наиболее используемым форматом веб-сервисов:
OAS значить OpenAPI specification, которую мы изучим дальше, в разделе Знакомство со спецификациями OpenAPI и Swagger. В отчете также встречаются API, не указанные выше - JMS API, которые используются для отправки сообщений Java.
Как можно видеть, когда дело доходит до API, один размер или тип подходит всем. Разработчики будут реализовывать API-интерфейс, который лучше всего соответствует их сценарию и требованиям, так же как используются различные типы автомобилей (спортивные автомобили, грузовики, полуприцепы, седаны и т.д.) для различных поездок, водителей, пассажиров и дороги.
На этом курсе мы будем разбираться с API REST. Помните, что с REST API пользователю не доставляются библиотеки или файлы. Вместо этого пользователи делают запросы к ресурсам на веб-сервере, а сервер возвращает ответы, содержащие информацию. И система, инициирующая запрос, и система, предоставляющая ответ, могут быть на любом языке программирования, если они передают сообщение через HTTP.
API REST работают по тому же протоколу, что и веб. Когда мы открываем браузер и вводим URL-адрес веб-сайта (например, https://google.com), мы фактически делаем запрос GET для ресурса на сервере. Сервер отвечает контентом, а браузер делает контент видимым.
Этот курс фокусируется не только на REST API, из-за их популярности и востребованности, но и потому, что они более доступны для технических авторов. Не нужно знать определенный язык программирования для документирования REST API. И REST становится наиболее распространенным типом API в любом случае.
Компании новички в разработке API
Исходя из отчета о состоянии API на 2019 все больше компаний начинают разработку API.
Сопутствующий график выглядит следующим образом:
Удивительно, что разработка API так бурно развивается в компаниях: «59% организаций начали разрабатывать API за последние пять лет». Если посмотреть на отчет о состоянии API на 2019, в котором приняли участие 2300 специалистов, можно обнаружить схожие темпы роста:
Разработка API, безусловно, является областью, которая является несколько новой для многих компаний, и направления, методы и пути к этой новой территории не ясны. На самом деле, в отчете «Состояние API на 2019» отмечается, что компании решительно требуют большей стандартизации в этой области.
Programmableweb.com составляет график и отслеживает количество веб-API, добавленных в их каталог. Programmableweb пишут: «С января 2014 года в среднем добавляется более 2000 API в год» (исследования показывают, что интерес к предоставлению API все еще высок).
API eBay в 2005 году был одним из первых веб-API, который позволял продавцам управлять своими продуктами в своих магазинах eBay. С тех пор наблюдается огромный рост в веб-API. Учитывая важность четкой и точной документации по API, это дает прекрасную рыночную возможность для технических писателей. Технические писатели могут применить свои навыки общения, чтобы заполнить пробел на быстро растущем рынке.
Причины роста API
Почему API-интерфейсы такую популярность, что можно ввести название компании, а затем «API» и перейти на страницу документации для разработчиков этой компании? Одна из причин заключается в том, что сама сеть превращается в конгломерат API. Вместо огромных, универсальных систем веб-сайты используют API-интерфейсы, в которых они нуждаются.
Например, вместо того, чтобы создавать собственный поиск для поддержки своего веб-сайта, можно воспользоваться API сервиса поиска Algolia. Вместо того, чтобы создавать свой собственный платежный шлюз, можно интегрировать Stripe API. В качестве сервиса авторизации можно использовать UserApp API. Вместо того, чтобы создавать собственную систему электронной коммерции, можно использовать Snipcart API.
Практически каждый сервис предоставляет свою информацию и инструменты через API. Jekyll, популярный генератор статических сайтов, не имеет всех компонентов, необходимых для запуска сайта. Здесь нет интеграции новостных рассылок, аналитики, поиска, комментирования, форм, чата, электронной коммерции, опросов или других систем. Вместо этого на своем сайте Jekyll можно подключить нужные сервисы. (CloudCannon собрал длинный список сервисов, которые можно интегрировать в свой сайт.)
Такая модель в стиле кафе заменяет массивную модель швейцарской армии, которая пытается сделать все и вся. Лучше полагаться на специализированные компании в создании мощных и надежных инструментов (таких как поиск) и использовать их сервис, а не пытаться создавать все эти сервисы самостоятельно.
Каждый сайт использует свой сервис, как правило, через REST API. Получается, сеть становится переплетением множества различных сервисов и API, взаимодействующих друг с другом.
Необходимость документации API
Итак, мы установили, что API находятся на подъеме, следуя модели Интернета, и что API-интерфейсы REST лидируют в мире как наиболее распространенный тип API. Но как насчет документации для них?
На вопрос «Какие три наиболее важных характеристики вам нужны в API?», в отчете «Состояние API 2019» обнаружили, что «Точная и подробная документация» занимает третье место по важности:
Этот пункт поднялся на три позиции вверх по сравнению с аналогичным отчетом за 2016 год, где «Точная и подробная документация» занимала лишь 6 место.
И даже в более раннем опросе 2013 года Programmableweb.com пункт «Полная и точная документация» заняла первое место.
John Musser, один из основателей Programmableweb.com, подчеркивает важность документации в своих презентациях. В 10 причинах, по которым разработчики ненавидят ваш API, он говорит, что причина, по которой разработчики ненавидят ваш API, состоит в том, что «ваша документация - отстой».
Несмотря на то, что такие выводы могут стать четким требованием для создания отличной документации API, технические писатели не всегда занимаются этим. В Отчет о состоянии API в 2019 году указано следующее:
Конечно, вывод о том, что “только 15% участников вкладывают средства в технических писателей” расстроит технических писателей. К счастью, этот вопрос сформулирован плохо и может выдавать столь неутешительные ответы. Формулировка предполагает, что использование технических писателей для создания документов является альтернативой созданию документов с помощью спецификации OpenAPI (OAS). На самом деле технические писатели должны сотрудничать с инженерами для создания справочной документации через OAS. Справочная документация составляет только часть необходимой документации (может быть, половину). В этом курсе рекомендуется создание справочной документации техническими писателями с использованием OAS. Подробнее в разделе Обзор форматов спецификаций REST API.
Таким образом, коннотация этого опроса искажает роль технического писателя. Авторы технических текстов не являются старшеклассниками, которые пользуются пером при утомительной ручной обработки документации (чаще чем автоматической генерацией с помощью OAS). Вместо этого многие технические писатели продвигают и защищают OAS как стандарт для создания справочных документов.
В Отчете о состоянии API в 2019 вопрос звучит несколько иначе: «Есть ли в вашей организации официальный процесс разработки документации API?» В отчете за 2016 год было установлено, что документы являются приоритетом примерно для половины респондентов:
Опять же, вопрос сформулирован расплывчато. Что такое «формальный процесс документирования»? Учитывая, что одним из ключевых продуктов Smartbear является SwaggerHub, который автоматически генерирует справочную документацию из спецификации OpenAPI, «процесс формальной документации» может означать создание документации из спецификации OpenAPI.
Повышенное внимание к документации API
Почему к документации API REST столько много внимания? Почему она так высоко котируется в опросах? Документация API REST важна, потому что REST следует архитектурному стилю, а не точному стандарту протокола.
Чтобы понять важность документации для REST API, полезно сравнить REST и SOAP. API REST немного отличаются от API SOAP, которые были популярны несколько лет назад. API-интерфейсы SOAP обеспечивают специальный формат сообщений для отправки запросов и получения ответов. Используя формат сообщения XML, SOAP очень специфичен и имеет файл WSDL (Web Service Description Language), в котором описывается, как взаимодействовать с API.
REST API не соответствуют стандартному формату сообщений. REST - это архитектурный стиль, набор рекомендуемых практик для отправки запросов и получения ответов. Чтобы понять формат запросов и ответов API REST, не нужно обращаться к спецификации сообщения SOAP или изучать файл WSDL. Надо просто обратиться к документации REST API.
Все API работают немного по-своему. Не существует единого способа ведения дел, поэтому такая гибкость и разнообразие подпитывают необходимость в точной и понятной документации. (больше о REST API в разделе Что такое REST API?) Поскольку API REST отличаются друг от друга, всегда нужна будет документация и технические писатели.
Подъем рынка вакансий технических писателей
Многие работодатели стремятся нанять технических писателей, которые могут создавать не только полную и точную документацию, но и создавать стильные материалы для своей документации. Вот сообщение о вакансии от рекрутера, ищущего кого-то, кто может подражать документации Dropbox:
Как видите, клиент хочет найти «кого-то, кто будет подражать документации Dropbox».
Почему внешний вид документации так важен? Документация API не имеет пользовательского интерфейса для просмотра. Документация сама является интерфейсом. Работодатели знают это, поэтому они хотят убедиться, что у них есть нужные ресурсы, чтобы их документы API выделялись как можно лучше.
Вот как выглядит сайт документации Dropbox API:
Это ведь не сложный дизайн. Но его простота и краткость делают его привлекательным. Если учесть, что документация по API в большей или меньшей степени является интерфейсом продукта, создание четкого, современно оформленного сайта документации имеет первостепенное значение для доверия и привлекательности на рынке. (об этом поговорим в разделе Квалификация технического писателя.) Технический писатель с сильными техническими навыками и опытом написания документации для разработчиков, может получить практически любую работу. Например в Кремниевой долине такой специалист может претндовать на зарплату в 100-150 тыс. долларов или более.
Документация API - новинка для технических писателей
Документация по API часто в новинку для технических писателей. Многие из компонентов могут отличаться от традиционной документации интерфейсов. Например, все эти аспекты документации для разработчиков отличаются от традиционной документации:
- инструменты создания документации;
- целевая аудитория;
- языки программирования;
- тематические разделы;
- пользовательские задачи.
Пытаясь сориентироваться в мире документации API, можно изначально озадачиться различиями и испугаться инструментов и работе с кодом. Кроме того, само содержание документации часто является сложным и требует глубокого понимания процесса разработки.
В целом, техническим писателям очень интересен API. Этот курс поможет заложить основы того, что нужно знать, чтобы начать работать с документацией API и преуспеть в этой области. Став опытным техническим писателем API, мы будем пользоваться высоким спросом и будем играть важную роль в компаниях, которые распространяют свои услуги через API.