Руководство программиста по api

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

В прошлый раз мы сделали следующий запрос:

# Defining method (X), and headers (H):
cURL -X GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' -H 'Host: api.nasa.gov' -H 'Accept: text/html,application/xhtml+xml,application/xml'

# Or, alternatively can also be written verbose

# Using long form options
# Splitting cURL commands across multiple lines
# Line continuation character is represented in cURL by ``

cURL 
--request GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' 
--header 'Host: api.nasa.gov' 
--header 'Accept: text/html,application/xhtml+xml,application/xml'

Обратите внимание, что приведенный выше код не является JavaScript, и он выглядит иначе, чем код из нашего предыдущего примера. Он начинается с cURL (для клиентского URL), который представляет собой инструмент командной строки, используемый разработчиками для передачи данных.

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

Инструментарий cURL

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

• Postman: для тестирования веб-сервисов и генерации cURL сниппетов (и для нескольких других языков).
• cURL Converter (опционально): для преобразования команд cURL в JavaScript (и для некоторых других языков).

Итак, в этот раз давайте начнем использовать cURL для представления вызовов API, с которыми мы будем работать с помощью Postman (платформа для создания и использования API).

Использование Postman

Отправка первого запроса

Postman позволяет легко создавать и отправлять API-запросы. Вам не нужно вводить команды в терминале или писать какой-либо код. В его графическом интерфейсе достаточно просто создать новый запрос (например, используя данные из фрагмента cURL) и нажать кнопку Send. Ответ API появляется прямо внутри Postman.

Если вы никогда раньше не пользовались Postman, давайте сделаем это шаг за шагом.

Как войти в Postman:

1. Войдите с помощью Google (или электронной почты/имени пользователя) в Postman
2. Заполните информацию о пользователе (имя и роль, John Doe, Fullstack Developer).
3. Продолжить без команды

Создание HTTP-запроса с помощью cURL и Postman

Итак, давайте возьмем наш фрагмент cURL и импортируем его в Postman. Чтобы сделать это:

1. В личном рабочем пространстве нажмите на иконку + New HTTP Request, чтобы сразу же отправить запрос. В качестве альтернативы, используйте инструмент Импорт и вставьте фрагмент cURL, представленный выше, чтобы сэкономить время,
2. Если вы импортируете (если нет, пропустите этот шаг), появится модальное/всплывающее окно, в котором вы импортируете спецификации API как Raw Text, нажмите Continue и подтвердите, нажав Import.
3. Нажмите на Отправить и
4. Просмотрите ответ прямо в Postman.

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

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

Методы HTTP-запросов

Как мы уже говорили, архитектурный стиль REST использует все преимущества HTTP, поэтому, в свою очередь, любой RESTful API также унаследует их. На самом базовом уровне запрос API включает в себя URL конечной точки ресурса и метод запроса HTTP. Метод запроса HTTP (также называемый HTTP-глаголами) указывает на желаемое действие, которое вы хотите выполнить для данного ресурса.

Все методы HTTP-запросов имеют общие черты: они безопасны, идемпотентны и кэшируемы. Рассмотрим наиболее распространенные методы:

• GET извлекает данные из API
• POST отправляет новые данные в API
• PATCH и PUT обновляют существующие данные
• DELETE удаляет существующие данные

Давайте изучим эти методы HTTP с помощью нашей первой коллекции Postman.

Коллекции Postman

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

Вы можете создать коллекцию следующим образом:

• Сохранив один запрос и воспользовавшись быстрой ссылкой Новая коллекция во всплывающем окне/модальном меню ИЛИ
• нажав на значок + на вкладке Обзор (левое меню) вашего рабочего пространства.

Теперь, когда вы знаете, как создать коллекцию Postman, давайте быстро обсудим, как поделиться результатами работы Postman.

Экспорт данных Postman

Вы можете экспортировать свои коллекции Postman в файлы JSON для последующего использования из любого экземпляра Postman или использовать их с помощью инструмента CLI, например, Newman (инструмент, позволяющий запускать коллекции Postman из командной строки). Нажмите на Export или Share в любом месте папки с коллекцией. Отсюда у вас есть следующие возможности:

• Отправить коллекцию по электронной почте для совместной работы (аналогично предыдущему варианту экспорта).
• Экспорт в виде файла JSON
• Через JSON ссылку, которая генерирует статический снимок вашей коллекции (подобно тому, что я предоставил ранее).

Заключение

Postman имеет более 135 тысяч опубликованных коллекций, которые вы можете использовать для изучения нескольких различных API. Компании активно используют Postman не только для разработки и тестирования своих API, но и для быстрого создания прочной базы документации и предоставления ее миру. Для всех публичных коллекций Postman существуют категории AI, Communication, Data Analytics, Developer Productivity, DevOps, Financial Services, поэтому обязательно ознакомьтесь с ними и продолжайте учиться работать с API.

ПРИМЕЧАНИЕ: Эта статья относится к продолжающемуся циклу статей, который все еще находится в процессе работы. Если вы еще не читали, ознакомьтесь с частью 1: Введение в API. Часть 3: Руководство для начинающих по тестированию API.

Спасибо за прочтение.

Edit me

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

Цель раздела “Начало работы”

Раздел «Начало работы» это как Hello World для разработчиков, только с API. “Начало работы” ведет за руку пользователя от начала до конца при создании простейшего возможного вывода с системой. Для Hello World самым простым выводом является сообщение «Hello World». Для API это может быть успешный ответ на самый простой запрос.

И Hello World и “Начало работы” преследуют одну и ту же цель: показать пользователю, как использовать инфраструктуру, API или какую-либо другую систему, для получения простого и легкого результата, чтобы пользователи получили полное представление о работе системы, API и т.д.

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

Раздел “Начало работы” может содержать следующие пункты:

• Войти в аккаунт;
• Получить API ключ;
• Создание запроса
• Оценка ответа.

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

Кнопка Run in Postman

В разделе “Начало работы” можно рассмотреть возможность добавления кнопки Run in Postman. (Postman — это клиент REST API GUI, который мы изучили ранее в разделе Отправка запросов в Postman.) Если есть конечные точки API, интегрированные с Postman, можно экспортировать свои коллекции Postman в виде виджета для встраивания в HTML-страницу.

Run in Postman это кнопка, которая при нажатии импортирует информацию об API в Postman, чтобы пользователи могли выполнять вызовы с помощью клиента Postman. Таким образом, кнопка Run in Postman позволяет импортировать интерактивный пробный интерфейс API для конечных точек на веб-страницу.

Чтобы добавить кнопку Run in Postman, можно импортировать спецификацию OpenAPI в Postman или ввести информацию об API вручную. Стоит изучить раздел “Postman/docs”, как создать кнопку Run in Postman.

Множество демонстраций Run in Postman можно посмотреть здесь. Многие из этих демонстраций перечислены в сети API Postman.

Вот демо Run in Postman с использованием конечной точки weather API OpenWeatherMap (с которой мы работали раннее ):

Если нажать на кнопку, будет предложено открыть коллекцию в клиенте Postman:

Postman предоставляет мощный клиент REST API, с которым знакомы многие разработчики. Postman позволяет пользователям настраивать ключ и параметры API и сохранять эти значения. Хотя Postman не имеет возможности вызова в браузере, как в Swagger UI, во многих отношениях клиент Postman более полезен, поскольку позволяет пользователям настраивать и сохранять сделанные ими запросы. Postman — тот инструмент, который внутренние разработчики часто используют для хранения запросов API при тестировании и изучении функциональности.

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

Если в документации еще нет функции Try it out, кнопка Run in Postman предоставляет такую интерактивность простым способом, не требуя жертв со стороны единственного источника знаний для документации.

Недостатком является то, что в Postman не попадают описания параметров и конечных точек. Кроме того, если пользователи незнакомы с Postman, им может быть трудно понять, как им пользоваться. Редакторы Try it out, которые запускаются непосредственно в браузере, как правило, более просты и лучше интегрируют документацию.

Примеры разделов “Начало работы”

Ниже приведены несколько примеров разделов “Начало работы” в API. Если сравнить различные разделы «Начало работы», можно увидеть, что некоторые из них являются подробными, а некоторые — высокоуровневыми и краткими. В общем, чем дольше можно вести разработчика за руку, тем лучше. Тем не менее, раздел должен быть кратким, а не многословным с другой документацией. Ключевым моментом является то, чтобы показать пользователю полный, от и до, процесс работы с API.

Paypal

“Начало работы” Paypal содержит довольно много деталей, начиная с авторизации, запросов и других деталей до первого запроса. Хотя этот уровень детализации не так краток, он помогает сориентировать пользователей на необходимую им информацию. Чистый и понятный формат.

Twitter

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

Parse Server

Раздел “Начало” работы в Parse Server содержит большое количество деталей и подробное описание различных этапов. Для более подробных шагов по подключению вашего приложения и запуску сервера в другом месте, в разделе размещена ссылка на дополнительную информацию.

Adsense

“Начало работы” Adsense выделяет некоторые основные предпосылки для начала работы на платформе. После того, как вы настроитесь, он предоставляет «краткое руководство по началу работы». Такое руководство знакомит пользователей с простым сценарием от начала до конца, помогая им понять продукт и его возможности.

Aeris

Начало работы в сервисе погоды Aeris предоставляет информацию для настройки приложения, а затем делает запрос на одном из нескольких популярных языков. Хотя показ кода на определенных языках, несомненно, более полезен для программистов, использующих данный язык, примеры кода могут быть неуместны для других пользователей (например, разработчики Java могут найти код Python неуместным, и наоборот). Фокусировка на определенном языке часто является компромиссом.

Watson and IBM Cloud

В разделе “Начало работы” Watson и IBM Cloud перечислены три шага. Тем не менее, это не полное руководство по началу работы. Пользователь может только выбрать сервис для своего проекта. В итоге кодировать начинаем с помощью Watson Dashboard.

В идеале, раздел “Начало работы” должен помочь пользователю увидеть ощутимые результаты, но возможно ли это или нет, зависит от API.

👨‍💻 Практическое занятие: Раздел “Начало работы”

В своем найденном опен-сорс проекте найдем раздел “Начало работы” и ответим на следующие вопросы:

• Есть ли у API раздел “Начало работы”?
• Описан ли процесс начала работы от и до в разделе?
• Можно ли успешно выполнить все шаги в разделе?
• Сколько времени занимает освоение раздела?
• Отобразятся ли предположения о вашем техническом уровне в документации при попытках упростить инструкцию?

🔙

Go next ➡

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

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

Когда пользователи делают запросы к API или посещают интернет-магазин, они ожидают быстрого ответа. Поэтому необходимо оптимизировать Magento TTFB (Time To First Byte) или использовать другие стратегии повышения производительности, которые лучше работают для выбранной CMS.

Причины для интеграции API:

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

2. Обзор REST API

RESTful относится к программной архитектуре, которая расшифровывается как Representational State Transfer (Передача репрезентативного состояния). Эта архитектура известна в контексте стандартизации использования систем обмена информацией (веб-сервисов).

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

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

2.1. Использование интернета

Для REST нет специальной клиентской технологии, поскольку REST подходит для различных проектов, таких как:

1. Веб-разработка.
2. iOS-приложения.
3. IoT-устройства.
4. Windows Phone приложения.

Поскольку не требуется придерживаться конкретного клиентского стека, допустимо построить любую инфраструктуру для своей компании.

2.2. Приложения в облаке

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

2.3. Облачные вычисления

Соединение API с сервисом требует управления декодированием URL-адреса. Поэтому REST стал полезным в облачных сервисах. Архитектура RESTful API станет стандартом в будущем благодаря облачным вычислениям и микросервисам.

3. Как работают REST API?

Данные (такие как изображения, видео и текст) воплощают ресурсы в REST. Клиент посещает URL-адрес и отправляет серверу запрос, чтобы получить ответ.

4. Концепции REST API

Запрос (URL, к которому обращаетесь) содержит четыре компонента:

1. Конечная точка, являющаяся URL-адресом со структурой root-endpoint/?.
2. Метод с типом (GET, POST, PUT, PATCH, DELETE).
3. Заголовки, выполняющие функции аутентификации, предоставление информации о содержимом тела (допустимо использовать параметр -H или --header для отправки заголовков HTTP) и т. д.
4. Данные (или тело) – это то, что отправляется на сервер с помощью опции -d или --data при запросах POST, PUT, PATCH или DELETE.

HTTP-запросы разрешают работать с базой данных, например:

1. POST-запрос для создания записей.
2. GET-запрос на чтение или получение ресурса (документа или изображения, набора других ресурсов) с сервера.
3. PUT и PATCH-запросы для обновления записей.
4. DELETE-запрос на удаление ресурса с сервера.

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

Сервер отправляет данные клиенту в формате:

1. HTML.
2. JSON (распространённый формат благодаря независимости от компьютерных языков и доступности для людей и машин).
3. XLT.
4. PHP.
5. Python.
6. Текст.

5. Зачем использовать REST API?

Преимущество REST над другими API, такими как SOAP в масштабируемости, гибкости, переносимости и независимости.

5.1. Не полагаться на структуру проекта

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

5.2. Портативность и адаптивность

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

5.3. Масштабирование проекта в будущем

Поскольку клиент и сервер действуют независимо, программисты могут быстро разработать продукт.

6. Особенности стиля архитектуры RESTful

Разработчикам приходится учитывать жёсткую структуру некоторых API, таких как SOAP или XML-RPC. Но REST API — это другое. REST API поддерживают широкий спектр типов данных и могут быть написаны практически на любом языке программирования.

Шесть архитектурных ограничений REST являются принципами разработки решения и заключаются в следующем:

6.1. Унифицированный интерфейс (последовательный пользовательский интерфейс)

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

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

6.2. Разделение клиента и сервера

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

Например, у клиента только универсальный идентификатор запрошенного ресурса (URI) и не может общаться с серверной программой другим способом. Однако, сервер не должен влиять на клиентское ПО. Поэтому сервер отправляет данные по HTTP. Это означает что, если клиентский код изменится, это не повлияет на работу сервера.

Клиентские и серверные программы могут быть модульными и независимыми до тех пор, пока каждая сторона знает, какой формат сообщения доставлять другой. Отделение пользовательского интерфейса от ограничений хранения данных улучшает гибкость интерфейса на разных платформах и повышает масштабируемость.

Кроме того, каждый компонент выигрывает от разделения, поскольку может развиваться независимо. Интерфейс REST помогает клиентам:

1. Иметь доступ к одним и тем же конечным точкам REST.
2. Выполнять одинаковые действия.
3. Получать одинаковые ответы.

6.3. Нестационарная связь между клиентами и серверами

Системы на основе REST не имеют состояния, то есть состояние клиента остаётся неизвестным для сервера и наоборот. Это ограничение разрешает серверу и клиенту понимать отправленное сообщение, даже если они не видели предыдущие.

Чтобы обеспечить соблюдение этого ограничения без статичности, требуется использовать ресурсы, а не команды. Это имена существительные в сети. Их цель – описать объект, который требуется сохранить или передать другим службам.

Допустимо контролировать, изменять и повторно использовать компоненты, затрагивая систему частично, поэтому преимущества этого ограничения включают достижение:

• стабильности;
• скорости;
• масштабируемости RESTful-приложений.

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

6.4. Кэшируемые данные

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

Это также даёт серверу больше возможностей масштабирования благодаря меньшей нагрузке на сервер. Кэширование увеличивает скорость загрузки страниц и разрешает получить доступ к ранее просмотренному контенту без подключения к интернету.

6.5. Архитектура многоуровневой системы

Следующее обсуждаемое ограничение — это многоуровневая структура RESTful. Этот принцип включает в себя группировку слоёв с определёнными функциями.

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

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

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

6.6. Кодирование по требованию (необязательно)

Предоставление статических представлений ресурсов в формате XML или JSON — популярный сценарий использования REST API.

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

7. Проблемы, которые следует ожидать при использовании REST API

С пониманием дизайна REST API и архитектурного ограничения, необходимо знать о проблемах, которые следует ожидать при использовании этого архитектурного стиля:

7.1. Соглашение по конечным точкам REST

API-интерфейсы должны оставаться единообразными независимо от конструкции URL. Но с ростом возможных комбинаций методов становится труднее поддерживать единообразие в больших кодовых базах.

7.2. Версионность как свойство REST API

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

7.3. Множество методов аутентификации

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

Но 20 методов авторизации могут затруднить первоначальный вызов API. Поэтому разработчики не продолжают проект из-за первоначальных трудностей.

7.4. Уязвимости безопасности REST API

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

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

7.5. Чрезмерный сбор данных и запросы

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

***

Подведение итогов

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

Материалы по теме

• Как превратить базу данных в RESTful API
• 🛠 Хватит использовать REST для API!
• Разбираем по косточкам компьютерные сети: HTTP, TCP, REST
• 😎✔️ 15 лучших практик разработки и проектирования REST API

Время на прочтение
8 мин

Количество просмотров 4.4K

Это глава 30 моей бесплатной книги про 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 и работаете над их улучшением.

Была ли эта статья полезна для вас?

Да / Нет