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

Содержание:

Дизайн в три колонки

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

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

Многие API смоделировали свой дизайн после Stripe. Например, Slate, Spectacle или Readme.io. Следует ли использовать Дизайн в три колонки с документацией по API? Может быть.

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

MYOB Developer Center использует интересный подход к документированию JSON в своих API. Они перечисляют структуру JSON в виде таблицы, с разными уровнями отступов. Можно навести курсор мыши на поле с для появления всплывающей подсказки с описанием или щелкнуть по полю, чтобы раскрыть описание ниже. Использование всплывающих подсказок позволяет идеально выровнять строки, содержащие пример и описание.

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

Публикация и управление API

Магазин хром

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

Тестирование API

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

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

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

Управление API

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

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

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

Авто генерация примеров кода

Как работать с классической версией google книг

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

Paw (на MacOS) позволяет экспортировать запрос практически на все мыслимые языки:

После того, как мы сконфигурировали запрос (процесс похож на Postman), можно сгенерировать фрагмент кода, выбрав Файл> Экспорт запроса.

Приложение Postman также может генерировать фрагменты кода аналогичным образом. Мы рассмотрели этот процесс раннее в разделе Изучение полезных данных JSON ответа. В Postman после конфигурации запроса, кликаем ссылку (которая появляется под кнопкой «Сохранить» в правом верхнем углу).

Затем выбираем нужный язык, например JavaScript> Jquery AJAX:

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

(Для практики, включающей использование сгенерированного кода jQuery из Postman, открываем разделы Изучение полезных данных JSON ответа и Доступ и вывод на страницу определенного значения JSON.)

API для трансмиссионных масел

Как протестировать компьютер на стабильность

Трансмиссионные масла классифицируются Американским институтом нефти с использованием рейтингов GL. Например, большинству современных редукторов требуется масло GL-4, а отдельные дифференциалы (если они установлены) требуют масла GL-5

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

Оценки вязкости API для трансмиссионных масел напрямую не сопоставимы с характеристиками для моторного масла, и они тоньше, чем показывают цифры. Например, многие современные редукторы используют трансмиссионное масло 75W90, которое фактически эквивалентно вязкости для моторного масла 10W40. Многоцелевые трансмиссионные масла становятся все более распространенными; в то время как трансмиссионное масло не достигает температур моторного масла, оно заметно нагревается по мере того, как автомобиль приводится в движение, главным образом из-за сдвигового трения (с небольшим количеством теплопроводности через колокольчик из блока цилиндров).

Наименование стандарта	Статус	Год выпуска	Ссылка
GL-1 Полную информацию о стандарте GL-1 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее
GL-2 Полную информацию о стандарте GL-2 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее
GL-3 Полную информацию о стандарте GL-3 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее
GL-3+ Полную информацию о стандарте GL-3+ API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее
GL-4 Полную информацию о стандарте GL-4 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	1995	Подробнее
GL-4+ Полную информацию о стандарте GL-4+ API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	1995	Подробнее
GL-5 Полную информацию о стандарте GL-5 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	1995	Подробнее
GL-5 LS Полную информацию о стандарте GL-5 LS API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	1995	Подробнее
GL-6 Полную информацию о стандарте GL-6 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее
MT-1 Полную информацию о стандарте MT-1 API вы можете получить, нажав на ссылку подробнее.	Действующий стандарт	нет информации	Подробнее

Тестовые потоки

Давайте разделим и обозначим три вида потоков тестирования, которые составляют наш план тестирования:

Изолированное тестирование запросов — выполнение одного запроса API и соответствующая проверка ответа. Такие базовые тесты — это минимальные строительные блоки, с которых мы должны начинать. И нет смысла продолжать тестирование, если эти тесты упадут.
Многоступенчатый рабочий поток с несколькими запросами — тестирование серии запросов, которые являются обычными действиями пользователя, поскольку одни запросы могут зависеть от других. Например, мы выполняем запрос POST, который создает ресурс и возвращает автоматически сгенерированный идентификатор в своем ответе. Затем мы используем этот идентификатор, чтобы проверить, присутствует ли этот ресурс в списке элементов, полученных запросом GET. Затем мы используем PATCH для обновления новых данных и снова вызываем запрос GET для проверки этого обновления. И в завершении, мы УДАЛЯЕМ этот ресурс и снова используем GET, чтобы убедиться, что записи больше нет.
Комбинированные тесты API и тесты веб-интерфейса — это в основном относится к ручному тестированию, при котором мы хотим обеспечить целостность данных и согласованность между пользовательским интерфейсом и API.

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

Открытые API — мода или необходимость?

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

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

Российское государство и его финансовый сектор уже осознали необходимость открытого банкинга. Предоставление банковских API внешним организациям признано ключевым элементом, необходимым для эффективной интеграции систем участников финансового рынка, инициативы выпуска открытых API поддерживают Центробанк, портал Банки.ру, Московская биржа, «Национальный клиринговый центр» и «Национальный расчетный депозитарий». Отдельные банки уже сформулировали свою стратегию открытого банкинга, определились с моделью дальнейших действий, официально анонсировали доступ к своим системам и сервисам через открытые API и приступили к соответствующим работам.

Список API на webMethods API portal

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

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

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

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

Но управление открытыми API никому не дано свыше. Оно невозможно без соответствующего технологического стека.

Запросы на разных языках

Как было сказано ранее в разделе Что такое REST API? REST API не зависит от языка. Универсальный протокол помогает облегчить широкое распространение для разных языков программирования. Разработчики могут кодировать свои приложения на любом языке, от Java до Ruby, JavaScript, Python, C #, Node JS или каком-либо еще. Пока разработчики могут отправлять HTTP-запросы на своем языке, они могут использовать API. Ответ от веб-запроса будет содержать данные в формате JSON или XML.

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

Однако некоторые API отображают простые запросы на разных языках. Вот пример из Twilio:

в выпадающем списке можно выбрать, какой язык использовать для примера запроса: C #, curl, Java, Node.js, PHP, Python или Ruby.

Вот еще пример API от Clearbit:

Можно увидеть запрос в Shell (curl), Ruby, Node или Python. Разработчики могут легко скопировать необходимый код в свои приложения, вместо того чтобы выяснить, как заставить запрос curl перевести на определенный язык программирования.

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

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

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

Тестирование API без документации

Если Вам по какой-то причине предстоит проделать эту неблагодарную работу,
определетесь, насколько всё плохо. Какая у Вас есть информация об объекте
тестирования.

Известно ли какие порты для Вас открыты? Знаете ли Вы нужные endpoints?

Сканирование портов

Если дело совсем труба — просканируйте порты, например, с помощью netcat.
Открытые порты сохраните в файл

openports.txt

nc -z -v answerit.ru 1-10000 2>&1 | grep succeeded > openports.txt

Эта операция займёт довольно много времени. Можете почитать советы по работе с

Nmap и Netcat

, например, следующие:

Перебор запросов

Если Вам известен нужный порт и соответствующий endopoint переберите все возможные HTTP
. Начните с наиболее очевидных:

POST
PUT
GET

Для ускорения процесса напишите скрипт на

Bash

или

Python
.

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

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

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

Пример API и тестовая матрица

Теперь мы можем отобразить все в виде матрицы и использовать ее для написания подробного плана тестирования (для автоматизации тестирования или ручных тестов).

Предположим, что подмножеством нашего API является конечная точка /users, которая включает следующие вызовы API:

Вызов API	Действие
GET /users	Просмотреть всех пользователей
GET /users?name={username}	Получить пользователя по имени пользователя
GET /users/{id}	Получить пользователя по ID
GET /users/{id}/configurations	Получите все конфигурации для пользователя
POST /users/{id}/configurations	Создать новую конфигурацию для пользователя
DELETE /users/{id}/configurations/{id}	Удалить конфигурацию для пользователя
PATCH /users/{id}/configuration/{id}	Обновить конфигурацию для пользователя

Где {id} — это UUID, а все конечные точки GET позволяют фильтровать, сортировать, исключать и ограничивать дополнительные параметры запроса для фильтрации, сортировки и разбивки на страницы тела ответа.

Основные позитивные тесты (позитивный путь по умолчанию)Позитивные тесты + необязательные параметры проверокНегативное тестирование – валидный ввод данныхНегативное тестирование — неверные входные данныеДеструктивное тестирование

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

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

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

Уровни зрелости API

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

Безопасность и авторизация

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

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

Проверка протокола: проверьте HTTP / HTTPS в соответствии со спецификацией

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

Политики ограничения скорости, троттлинга и политики контроля доступа

Нагрузочные тесты (позитивные), стресс-тесты (негативные)

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

Swagger

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

Код

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Повторюсь, ведь от актуальности документации API зависит качество разработки ПО.

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

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

SQL

Начинаем вполне естественно с SQL. Кто ж его не знает?

Для изучения SQL есть гигантское количество учебных курсов и книг. Мы будем опираться на https://sqlzoo.net. Это хороший начальный онлайн курс по SQL с примерами, прохождением заданий и справочником языка.

Будем переносить задачки из SQLZoo на платформу IRIS и получать аналогичные решения разными способами.

Перенесём данные с SQLZoo в хранилище нашего собственного экземпляра IRIS. Для этого:

Более подробно о работе с SQL через портал управления можно посмотреть в документации.

Готовые скрипты для развёртывания базы данных и набора тестовых данных SQLZoo есть в описании на сайте в разделе Данные.

Пара прямых ссылок для таблицы World:

http://sqlzoo.net/w/index.php?title=Createworld.txt&action=raw a script to create the world database
http://sqlzoo.net/w/index.php?title=Tabworld.txt&action=raw the data to go in that table

Скрипт для создания базы данных можно выполнить тут же на портале управления IRIS в форме «Исполнитель запросов».

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

Проверяем наличие таблицы с данными запуском простейшего скрипта в форме «Исполнитель запросов»:

Теперь нам доступны примеры и задания с сайта «SQL Zoo». Все примеры ниже реализуют SQL запрос из первого задания:

Так что можете смело продолжать начатое нами исследование API перенося задания из SQLZoo на платформу IRIS.

Что бы плавно перейти к следующему шагу — объектный доступ к нашей базе данных, сделаем небольшой промежуточный шаг от «чистых» SQL запросов к SQL запросам встроенные в код приложения на ObjectScript — объектно-ориентированном языке, встроенном в IRIS.

В ответ должны вернуться название страны и число жителей.