Работа с api что это

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

API для infohound.ru — это скрипт, который принимает запросы (по методам GET, POST) и отдаёт не обычный HTML для браузеров, а результат запроса в определённом формате (JSON). Предназначен он не пользователям, а скрипту со стороннего сайта/сервиса/программы, который посылает эти GET/POST запросы, получает результат и как-то использует данные. Посылает он запросы естественно не просто так, а чтобы выполнить определённое действие (напр. как действия которые выполняют пользователи сайта через браузер).

Пользователям-программистам он нужен для интеграции с другими сайтами/сервисами/программами, или автоматизации некоторых действий, создав программу для нашего сайта.

Так, например, Вы можете разработать свое собственное приложение для infohound.ru и управлять своими запросами вообще не посещая наш сайт. На самом деле API предоставляет огромные возможности и сфера применения API-интерфейсов ничем не ограничена. Появление API-интерфейса у сервиса infohound.ru поможет теперь нашим пользователям решать самые неординарные задачи, интегрируясь с нашим сервисом. А количество функций нашего API-интерфейса со временем будет только расти.

Общая информация

• Авторизация осуществляется по протоколу OAuth2.0.
• Все данные доступны только в формате JSON.
• Базовый URL — https://infohound.ru/api

Терминология

Существует несколько видов HTTP-запросов. Тип запроса указывается в первой строке HTTP-пакета, которая имеет вид:

GET /api/check HTTP/1.1

GET-запрос

GET-запрос — это самый распространенный вид HTTP-запроса. При помощи него происходит запрос браузером любого файла веб-сервера. HTTP-запрос типа GET состоит только из HTTP-заголовков, тело у него отсутствует .

При помощи GET-запроса можно передать веб-серверу параметры — некоторую информацию. Например, передача id записи в нашей базе данных, которую вы хотите посмотреть. Рассмотрим механизм передачи параметров с помощью GET-запроса.

В первой строке запроса после ключевого слова GET помещается путь к запрашиваемому документу. Если в пути встречается знак вопроса, то принято считать, что в этом месте путь заканчивается, а за ним начинаются GET-параметры этого запроса:

GET https://infohound.ru/api/v1/request/view?параметры HTTP/1.1

GET-параметр имеет формат имя_параметра=значение_параметра, сами параметры разделяются знаком

client_id= — идентификатор, присвоенный вашему приложению при создании;

redirect_uri= — url для перенаправления пользователя после авторизации.

• state= — любая строка. В случае указания, будет включен в ответный редирект. Это позволяет исключить возможность взлома путём подделки межсайтовых запросов. Подробнее об этом: RFC 6749. Section 10.12

Правила формирования специального redirect_uri

К примеру, если в настройках сохранен http://www.example.ru , то разрешено указывать:

• http://www.example.ru/api — поддомен;
• http://www.example.ru/api/sub/path — уточнение пути;
• http://www.example.ru/api?lang=RU — дополнительный параметр;
• http://www.example.ru/api/sub/path?lang=RU — всё вместе.

• http://example.ru/ — без www (в случае если в настройках www указан);
• https://www.example.ru/api — различные протоколы;
• http://www.site.ru/ — другой путь;
• http://example.ru:80/api — указание изначально отсутствующего порта;

Получение access и refresh токенов

После получения authorization_code приложению необходимо сделать POST или GET запрос на

https://infohound.ru/oauth2/auth/token
для обмена полученного authorization_code на access_token .

• grant_type=authorization_code — тип авторизации;
• client_id= — идентефикатор вашего приложения;
• client_secret= — ваше секретное слово, указанное при создании приложения;
• code= — код авторизации, полученный вами;
• redirect_uri= — адрес, указанный вами при получении кода авторизации, как параметр, а не тот, который Вы указывали в настройках приложения.

В ответе вернётся JSON:

< «access_token»: «», «expires_in «: 1209600, «token_type»: «bearer», «scope»: «scope», «refresh_token»: «», >

• access_token — ваш access_token;
• expires_in — время его жизни в секундах;
• token_type — тип access_token;
• scope — права доступа;
• refresh_token — ваш refresh_token, необходимый для обновления пары access и refresh токенов.

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

Если обмен authorization_code произвести не удалось, то вернётся ответ с телом:

• message название ошибки. Например, invalid_request , если какой либо из обязательных параметров не был передан или неверно указан.
• description будет содержать дополнительное описание ошибки.

Обновление пары access и refresh токенов

access_token также имеет срок жизни (ключ expires_in , в секундах), при его истечении приложение должно сделать POST или GET запрос с refresh_token для получения нового.

https://infohound.ru/oauth2/auth/token?grant_type=refresh_tokenclient_id= «access_token»: «», «expires_in «: 1209600, «token_type»: «bearer», «scope»: «scope», «refresh_token»: «», >

• access_token — ваш access_token;
• expires_in — время его жизни в секундах;
• token_type — тип access_token;
• scope — права доступа;
• refresh_token — ваш refresh_token, необходимый для обновления пары access и refresh токенов.

После получения новой пары access и refresh токенов, их необходимо использовать в дальнейших запросах в api и запросах на продление токена.

Список методов

Вспомогательные методы (info)

Метод для проверки access_token (check)

После получения access_token Вы можете проверить его. Для проверки Вам необходимо отправить GET запрос на

https://infohound.ru/api/v1/info/check

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0

Вам вернётся ответ — строка вида

It works!

Возможные ошибки:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Методы для работы с запросами (request)

Создать запрос на поиск (create)

Одновременно можно создать не более 100 запросов.

Для создания запросов вам необходимо послать POST запрос с телом запроса в формате JSON на

https://infohound.ru/api/v1/request/create

Тело запроса должено иметь следующий вид:

Обязательные заголовки запроса:

• content-type: application/json

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0

Обязательные поля массива данных:

• last_name — фамилия (максимальная длина 255 символов)
• first_name — имя (максимальная длина 255 символов)
• birthday — день рождения (формат строго yyyy-mm-dd)
• living_city — город проживания (максимальная длина 255 символов)

Необязательные поля массива данных:

• middle_name — отчество (максимальная длина 255 символов)
• birthday_city — город рождения (максимальная длина 255 символов)
• comment — любой Ваш комментарий (максимальная длина 255 символов). Например id клиента в Вашей базе данных.

Вы можете создать несколько запросов за раз, например

Вам вернётся ответ в JSON формате вида

где id — идентефикатор добавленного запроса в нашей базе данных, comment — комментарий, который вы указали в запросе при его создании.

Если же Вы создаёте один запрос, например

вам вернётся найденная информация по данному запросу в формате JSON (посмотреть формат)

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

Возможные ошибки:

Вы отправили некорректное тело запроса:

Вы пытаетесь добавить более 100 запросов за раз:

Вы неверно указали аттрибут запроса. Например, забыли указать фамилию:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Вывести список запросов (list)

Для просмотра ваших запросов вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/list

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0

Необязательные параметры запроса:

• limit — число, сколько записей вернуть. За раз можно вернуть не больее 100 записей. Если Вы укажите limit больше 100, то его значение автоматически исправится на 100.
• offset — число, начиная с какой записи возвращать

В случае успешного выполнения запроса вам вернётся ответ в JSON формате вида

Возможные ошибки:

Параметр limit не число или меньше нуля:

Параметр offset не число или меньше нуля:

Список запросов пуст:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Удалить запрос (delete)

Для удаления запроса вам необходимо послать POST или GET запрос с телом запроса на

https://infohound.ru/api/v1/request/delete

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0
• id — id запроса в нашей базе данных, который Вы хотите удалить

В случае успешного выполнения запроса вам вернётся ответ в JSON формате вида

Возможные ошибки:

Отсутствует параметр id (или не число):

Запрос с таким id не существует или удалён:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Изменить запрос (update)

Для обновления запроса Вам необходимо послать POST запрос с телом запроса в формате JSON на

https://infohound.ru/api/v1/request/update

Тело запроса должено иметь следующий вид:

Обязательные заголовки запроса:

• content-type: application/json

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0
• id — id запроса в нашей базе данных, который Вы хотите обновить

Необязательные поля тела запроса:

• last_name — фамилия (максимальная длина 255 символов)
• first_name — имя (максимальная длина 255 символов)
• middle_name — отчество (максимальная длина 255 символов)
• birthday — день рождения (формат строго yyyy-mm-dd)
• living_city — город проживания (максимальная длина 255 символов)
• birthday_city — город рождения (максимальная длина 255 символов)
• comment — любой Ваш комментарий (максимальная длина 255 символов). Например id клиента в Вашей базе данных.

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

В случае успешного обновления вам вернётся ответ в JSON формате вида

Возможные ошибки:

Отсутствует параметр id (или не является числом):

Вы отправили некорректное тело запроса:

Запрос с таким id не существует или удалён:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Обновить запрос (refresh)

Обновить запрос — заново произвести поиск по тем же данным. Для обновления запроса вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/refresh

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0
• id — id запроса в нашей базе данных, который Вы хотите обновить

В случае успешного обновления вам вернётся ответ в JSON формате с полученными данными.
Его структура полностью совпедает с ответом при выполнении метода create.

Возможные ошибки:

Отсутствует параметр id (или не число):

Запрос с таким id не существует или удалён:

Вы передали неправильный access_token:

У переданного access_token истёк срок жизни:

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Получить данные по запросу (get)

Для проверки запроса вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/get

Обязательные параметры запроса:

• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0
• id — id запроса в нашей базе данных, который Вы хотите посмотреть ИЛИ
• access_token — access_token, полученный вами при регистрации приложения по протоколу OAuth2.0
• comment — Ваш комментарий (максимальная длина 255 символов), который был указан при создании запроса.

В случае, если отправлена пара access_token и id , проверка на готовность будет производится одного запроса с id нашей внутренней базы.

Вам вернётся ответ в JSON формате

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

Вам вернётся ответ в JSON формате, вида

Возможные ошибки:

Отсутствуют обязательные параметры (id или comment):

Источник: infohound.ru

Что такое API

Слово «API» мелькает в вакансиях даже для начинающих тестировщиков. То REST API, то SOAP API, то просто API. Что же это за зверь такой? Давайте разбираться!

— А зачем это мне? Я вообще-то web тестирую! Вот если пойду в автоматизацию, тогда да… Ну, еще это в enterprise тестируют, я слышал…

А вот и нет! Про API полезно знать любому тестировщику. Потому что по нему системы взаимодействуют между собой. И это взаимодействие вы видите каждый день даже на самых простых и захудалых сайтах.

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

Но даже если у вас нет интеграции с другими системами, у вас всё равно есть API! Потому что система внутри себя тоже общается по api. И пока фронт-разработчик усиленно пилит GUI (графический интерфейс), вы можете:

• скучать в ожидании;
• проверять логику работы по API

Что такое API

API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».

Если переводить на русский, это было бы слово «договор». Договор между двумя сторонами, как договор на покупку машины:

• мои обязанности — внести такую то сумму,
• обязанность продавца — дать машину.

Все используют слово «контракт». Так принято. К тому же это слово входит в название стиля разработки:

• Code first — сначала пишем код, потом по нему генерируем контракт
• Contract first — сначала создаем контракт, потом по нему пишем или генерируем код (в этой статье я буду говорить именно об этом стиле)

API — набор функций

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

Соответственно, API отвечает на вопрос “Как ко мне, к моей системе можно обратиться?”, и включает в себя:

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

Тут вы можете мне сказать:

— Хмм, погоди. Операция, данные на входе, данные на выходе — как-то всё это очень сильно похоже на описание функции!

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

И да! Вы будете правы в том, что определения похожи. Почему? Да потому что API — это набор функций. Это может быть одна функция, а может быть много.

Как составляется набор функций

Да без разницы как. Как разработчик захочет, так и сгруппирует. Например, можно группировать API по функционалу. То есть:

• отдельно API для входа в систему, где будет регистрация и авторизация;
• отдельно API для отчетности — отчет 1, отчет 2, отчет 3… отчет N. Для разных отчетов у нас разные формулы = разные функции. И все мы их собираем в один набор, api для отчетности.
• отдельно API платежек — для работы с каждым банком своя функция.
• .

Можно не группировать вообще, а делать одно общее API.

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

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

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

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

При чем тут слово «интерфейс»

— Минуточку, Оля! Ты же сама выше писала, что API — это Application programming interface. Почему ты тогда говоришь о контракте, хотя там слово интерфейс?

Да потому, что в программировании контракт — это и есть интерфейс. В классическом описании ООП (объектно-ориентированного программирования) есть 3 кита:

1. Инкапсуляция
2. Наследование
3. Полиморфизм

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

• что подать на вход;
• что получается на выходе;
• какие исключения нужно обработать.

Как вызывается API

Вызвать апи можно как напрямую, так и косвенно.

1. Система вызывает функции внутри себя
2. Система вызывает метод другой системы
3. Человек вызывает метод
4. Автотесты дергают методы

1. Пользователь работает с GUI

Вызов API напрямую

1. Система вызывает функции внутри себя

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

Это самый «простой» в использовании способ, потому что автор API, которое вызывается — разработчик. И он же его потребитель! А значит, проблемы с неактуальной документацией нет =)

Шучу, проблемы с документацией есть всегда. Просто в этом случае в качестве документации будут комментарии в коде. А они, увы, тоже бывают неактуальны. Или разработчики разные, или один, но уже забыл, как делал исходное api и как оно должно работать…

2. Система вызывает метод другой системы

А вот это типичный кейс, которые тестируют тестировщики в интеграторах. Или тестировщики, которые проверяют интеграцию своей системы с чужой.

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

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

Я подключаю подсказки по API. И теперь, когда пользователь начинает вводить адрес на моем сайте, он видит подсказки из Дадаты. Как это получается:

• Он вводит букву на моем сайте
• Мой сайт отправляет запрос в подсказки Дадаты по API
• Дадата возвращает ответ
• Мой сайт его обрабатывает и отображает результат пользователю

И, конечно, не забываем про кейс, когда мы разрабатываем именно API-метод. Который только через SOAP и можно вызвать, в интерфейсе его нигде нет. Что Заказчик заказал, то мы и сделали ¯_(ツ)_/¯

Пример можно посмотреть в Users. Метод MagicSearch создан на основе реальных событий. Хотя надо признать, в оригинале логика еще замудренее была, я то под свой сайт подстраивала.

Но тут фишка в том, что в самой системе в пользовательском интерфейсе есть только обычный поиск, просто строка ввода. Ну, может, парочка фильтров. А вот для интеграции нужна была целая куча доп возможностей, что и было сделано через SOAP-метод.

Функционал супер-поиска доступен только по API, пользователь в интерфейсе его никак не пощупает.

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

(что именно надо тестировать в API — я расскажу отдельной статьей чуть позднее)

3. Человек вызывает метод

1. Для ускорения работы
2. Для локализации бага (проблема где? На сервере или клиенте?)
3. Для проверки логики без докруток фронта

Для примера снова идем в Users. Если мы хотим создать пользователя, надо заполнить уйму полей!

Конечно, это можно сделать в помощью специальных плагинов типа Form Filler. Но что, если вам нужны адекватные тестовые данные под вашу систему? И на русском языке?

Заполнение полей вручную — грустно и уныло! А уж если это надо повторять каждую неделю или день на чистой тестовой базе — вообще кошмар. Это сразу первый приоритет на автоматизацию рутинных действий.

И в данном случае роль автоматизатора выполняет… Postman. Пользователя можно создать через REST-запрос CreateUser. Один раз прописали нормальные “как настоящие” данные, каждый раз пользуемся. Профит!

Вместо ручного заполнения формы (1 минута бездумного заполнения полей значениями «лпрулпк») получаем 1 секунду нажатия на кнопку «Send». При этом значения будут намного адекватнее.

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

Если вы нашли баг и не понимаете, на кого его вешать — разработчика front-end или back-end, уберите все лишнее. Вызовите метод без графического интерфейса. А еще вы можете тестировать логику программы, пока интерфейс не готов или сломан.

4. Автотесты дергают методы

Есть типичная пирамида автоматизации:

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

Слово API как бы намекает на то, что будет использовано в тестах ツ

• операция: загрузка отчета;
• на входе: данные из ручных или автоматических корректировок или из каких-то других мест;
• на выходе: отчет, построенный по неким правилам

• Ячейка 1: Х — Y
• Ячейка 2: Z * 6
• .

GUI-тесты — честный тест, робот делает все, что делал бы пользователь. Открывает браузер, тыкает на кнопочки… Но если что-то упадет, будете долго разбираться, где именно.

API-тесты — все то же самое, только без браузера. Мы просто подаем данные на вход и проверяем данные на выходе. Например, можно внести итоговый ответ в эксельку, и пусть робот выверяет ее, правильно ли заполняются данные? Локализовать проблему становится проще.

Unit-тесты — это когда мы проверяем каждую функцию отдельно. Отдельно смотрим расчет для ячейки 1, отдельно — для ячейки 2, и так далее. Такие тесты шустрее всего гоняются и баги по ним легко локализовать.

Косвенный вызов API

Когда пользователь работает с GUI, на самом деле он тоже работает с API. Просто не знает об этом, ему это просто не нужно.

То есть когда пользователь открывает систему и пытается загрузить отчет, ему не важно, как работает система, какой там magic внутри. У него есть кнопочка «загрузить отчет», на которую он и нажимает. Пользователь работает через GUI (графический пользовательский интерфейс).

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

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

И вот уже пользователь видит перед собой готовый отчет. Он вызвал сложное API, даже не подозревая об этом!

Что значит «Тестирование API»

В первую очередь, мы подразумеваем тестирование ЧЕРЕЗ API. «Тестирование API» — общеупотребимый термин, так действительно говорят, но технически термин некорректен. Мы не тестируем API, мы не тестируем GUI (графический интерфейс). Мы тестируем какую-то функциональность через графический или программный интерфейс.

Но это устоявшееся выражение. Можно использовать его и говорить “тестирование API”. И когда мы про это говорим, мы имеем в виду:

• автотесты на уровне API
• или интеграцию между двумя разными системами.

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

И если вы видите в вакансии «тестирование API», скорее всего это подразумевает умение вызвать SOAP или REST сервис и протестировать его. Хотя всегда стоит уточнить!

Резюме

API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».

Контракт включает в себя:

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

Источник: temofeev.ru

Работа с api что это

09.09.2016

Что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы. Очень полезная статья для технических писателей, которые хотят роста. Начинайте документировать API, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (Lois Patterson), технический писатель API из компании Global Relay (Канада).

Тяжело отследить, сколько раз API (Application Programming Interfaces, интерфейсы программирования приложений) сопровождают нашу жизнь каждый день или даже каждый час. Когда проходит ваша транзакция в PayPal или когда вас подбирает водитель Uber, само по себе API невидимо, и это более чем типично для пользовательского программного обеспечения. API используется даже тогда, когда вы встраиваете YouTube-видео в запись WordPress. При наличии сотен тысяч общедоступных API, доступных широчайшему кругу пользователей, компании находятся под большим давлением, чтобы их API были легки и удобны для использования. Не будет сюрпризом то, что рост количества вакансий, связанных с документированием API, огромен — он показывает разогретый рынок для технических писателей, которые специализируются на документировании API.

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

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

Так чего хотят пользователи API?

Что мы всегда говорим новым (и старым) техническим писателям? Узнайте ваших пользователей… и пишите c расчётом на этих пользователей. Поставьте себя на их место и поймите, что им необходимо знать, чтобы выполнить свою задачу.

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

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

Начните с разработки API

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

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

Как выглядит связная разработка? Давайте обратим внимание на REST API, которые наиболее популярны для использования на массовом рынке. REST (Representational State Transfer, «передача состояния управления») представляет собой набор принципов разработки API, которые зарекомендовали себя как исключительно эффективные в широком спектре очень разных API.

В типичном REST API набор существительных (объектов) взаимодействует с ограниченным набором глаголов (GET, PUT, POST, DELETE). Параметры каждого существительного должны следовать схожим шаблонам и соглашениям. Параметры должны иметь такие типы данных, которые имеют смысл и связаны между собой. Если параметр userID — строка, а customerID — число, вы введёте пользователя в заблуждение. Действия глаголов должны быть связными для всех объектов.

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

Первый опыт использования вашего API

Если вы новый пользователь сложного нового продукта, что вы в первую очередь захотите сделать? Успешно использовать его. Как указал мне эксперт по разработке документации Том Джонсон (Tom Johnson), пользователь должен иметь возможность получить быстрый успех с помощью скорейшего продвижения к «Привет, мир» при использовании API. Searchify, например, содействует использованию своего продукта с помощью этой простого урока «Привет, мир», а затем переходит к более сложным урокам.

Обратите внимание на тщательное конструирование шагов и как пользователю сообщают обо всех необходимых условиях для завершения урока. Урок позволяет пользователям выбрать язык программирования.

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

Какие инструменты и процессы использовать для документирования API?

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

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

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

Давайте рассмотрим несколько инструментов, которые вы можете использовать.

Основные принципы

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

Это требование по привлечению разработчиков к созданию документации означает, что вам нужен переносимый формат, который может быть доступен для любого текстового редактора. У вас может быть один разработчик, который работает в emacs, другой в vim, а третий в SublimeText, и никто из них не хочет изучать новый текстовый редактор. Мы все знаем, насколько привязанными могут быть технические писатели к собственным инструментом, будь то Microsoft Word или MadCap Flare, и с разработчиками то же самое. К счастью, файлы, создаваемые в различных текстовых редакторах, полностью совместимы в отличие от проприетарных инструментов. Документация API может создаваться в виде текстовых файлов, а затем обрабатываться в генераторе статичных сайтов для создания привлекательных веб-сайтов или PDF. Ниже указаны несколько текстовых редакторов, которые, как мне известно, популярны среди различных групп разработчиков:

• https://www.gnu.org/software/emacs/
• http://www.vim.org/
• https://notepad-plus-plus.org/
• https://www.sublimetext.com/

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

Markdown с генератором статичных сайтов

Markdown — популярный и несомненно вездесущий формат в наши дни. Markdown — простой язык разметки, который вы можете использовать в любом текстовом редакторе. Если у вас есть файлы, созданные в Markdown, вы затем используете генератор статических сайтов, например, Jekyll, приложение, которое преобразует файлы, созданные в Markdown, в форматы HTML, PDF и другие. Если ваша документация в формате Markdown размещена на Github, ваши документы автоматически преобразуются в HTML без каких-либо действий с вашей стороны (хотя вы можете настроить отображение).

Вы можете научиться писать на Markdown за минуты. Это просто. Разработчики из вашей команды знают и любят Markdown. Использование Markdown помогает вам убрать барьеры между командой работки и командой документирования.

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

Разметка reStructuredText с генератором статических сайтов Sphinx

reStructuredText похож на Markdown, но предоставляет больше функций и отчасти связан с разработкой в Python. Я ценю простоту, с которой вы можете делать вставки из файлов, создавать библиографические ссылки, использовать LaTeX для математических выражений и создавать связи между множеством наборов документации. Несмотря на то, что reStructuredText немного более сложен, чем Markdown, а установка вместе с генератором статических сайтов Sphinx также может принести сложности, большинство пользователей также находят его простым в использовании. Многие пользователи выбирают реализацию reStructuredText и Sphinx, предлагаемую ReadTheDocs, как описано здесь:

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

Несмотря на то, что Sphinx наиболее популярен, также доступен другой генератор статических сайтов для restructuredText — Nikolai.

RAML, Swagger и API Blueprint

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

Вы можете увидеть более глубокие примеры с помощью Watson API и их представлений Swagger. Watson — движок искусственного интеллекта, который выигрывает у игроков-людей в Jeopardy, но используется во множестве других контекстов.

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

Какие документы и контекст необходимо включать?

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

Йогешвор Срикришнан (Yogeshwar Srikrishnan), бизнес-архитектор в Rackspace, замечает, что «Наиболее важная часть опыта для разработчика, который потребляет API — документация для разработчика». В его статье о документировании REST API для Dzone подробно изложены многие важные аспекты документации для разработчиков.

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

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

Зажигайте пользователей креативно. Например, с API Интернета вещей (IoT) некоторые пользователи думают о путях связи элементов, о которых вы и представить не могли, что они могут работать вместе. Знаете ли вы, что у Roomba есть API и что вы можете использовать это API, чтобы превратить Roomba в музыкальный инструмент?

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

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

Новый пользователь Twitter API может начать с самого начала — набора ЧаВо.

Установка и настройка

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

Делайте обновления API удобными для пользователей

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

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

Выкладывать ли документацию в Интернет

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

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

Расположение документации онлайн на Github демонстрирует, что ваша компания ищет подходы к пользователям-разработчикам. Вы можете получать прямую обратную связь от разработчиков о том, что корректно и полезно, а что нет. Например, PayPal провёл серьёзную работу над контентом, доступным на Github, включая документацию. И быстрый взгляд на сайт Github, раздел SDK для PayPal для Android показывает, что документы были обновлены семь дней назад (на данный момент).

Тестируйте, тестируйте, тестируйте!

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

Некоторые обычные инструменты для тестирования REST API включают в себя curl и Postman. Вам может потребоваться помощь вашей команды разработчиков, чтобы заставить их работать у вас, но ваша команда, скорее всего, уже использует эти или похожие инструменты. С помощью curl или Postman вы создаёте запрос, который хотите протестировать, и проверяете, что возвращается корректный ответ. Типичным тестом может быть проверка различных комбинаций параметров, чтобы убедиться, что они работают корректно вместе.

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

В заключение

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

Источник: protext.su