Api

Как тестировать API

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

Этот тест api отличается от тестирования gui тем, что тут проверяют бизнес-логику и архитектуру утилиты.

Перед всеми проверками разработчики обязательно тщательно готовят среду, в которой начнут тестировать api:

• Обзорное тестирование включает в себя проверку работы приложения;
• Юзабилити-тест покажет насколько удобно пользоваться функциями приложениями, как хорошо оно взаимодействует с другими программными продуктами;
• Тест безопасности говорит сам за себя – он покажет как выполнено шифрование и аутентификация;
• Автоматизированный тест нужен для создания приложений и скриптов, которые непрерывно будут тестировать api;
• Режим документации был создан для тестирования полноты функций. Это финальный этап проверки программного интерфейса приложения, после которого можно начать анализ результатов.

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

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

Раздел «Начало работы» это как `Hello World`, только с API. Сколько времени понадобится разработчику, чтобы получить максимально простой ответ, используя ваш API?

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

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

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

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

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

Поместите ссылку на раздел “Начало работы” на домашней странице документации. Сделайте так, чтобы разработчики могли с легкостью использовать 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

Наиболее распространены во всемирной паутине так называемые Web API, которые используются в качестве платформы для создания HTTP-служб. Среди них выделяют:

• RPC (Remote Procedure Call ) – удаленный вызов процедур,
• SOAP (Simple Object Access Protocol) – простой протокол доступа к объектам,
• REST (Representational State Transfer ) – передача состояния представления.

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

Также API можно подразделять по типу доступа:

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

Использование реалистичных значений в примере ответа

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

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

API: прагматическое использование

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

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

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

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

Вы пишете код и программируете как профессионал.

И что теперь?

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

Но как?

Просто!

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

Какие протоколы API наиболее распространены?

Вот три наиболее распространенных протокола API, которые должен знать каждый:

SOAP 

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

• Цель SOAP — обеспечить нейтральность, расширяемость, независимость и многословность.
• Этот протокол в основном полагается на XML вместе со схемами, которые определяют его как протокол с очень строгой типизацией для обмена сообщениями.
• Каждая операция, которая будет определяться этой службой, определяется явно вместе со структурой запроса и ответа на основе XML для определенной операции.
• Каждый входной параметр здесь привязан и определен для такого типа, как строка, целое число или любой другой сложный объект.. 

SOAP помогает разработчикам вызывать процессы, запущенные в различных операционных системах, таких как Linux, macOS, Windows и т. Д., Для авторизации, аутентификации и взаимодействия с XML(Extensible Markup Language). Веб-протоколы, такие как HTTP, работают почти во всех операционных системах; следовательно, SOAP также позволяет своим клиентам вызывать веб-сервисы и получать ответы независимо от платформ и языков.

REST 

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

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

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

GraphQL

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

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

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

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

Что такое API?

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

• API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, API Геолокации (Geolocation API) предоставляет простые в использовании конструкции JavaScript для работы с данными местоположения, так что вы сможете, допустим, отметить своё расположение на карте Google Map. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++) для подключения к устройству GPS (или любому другому устройству геолокации), получения данных и передачи их браузеру для обработки вашей программой, но, как было сказано выше, эти детали скрыты благодаря API.
• Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.

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

• JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node. Но пока не будем останавливаться на этом.
• API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
• Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
• Библиотеки JavaScript — Обычно один или несколько файлов, содержащих . Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
• JavaScript фреймворки (frameworks) — Следующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно «писать» веб-приложение с нуля. Главное различие между фреймворками и библиотеками — «Обратное направление управления» ( “Inversion of Control” ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка — наоборот, фреймворк производит вызов кода разработчика.

Как использовать API

Основная функция API – построение эффективной коммуникации между программами. Для разных целей интерфейс выполняет разные задачи. 

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

В партнерском маркетинге

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

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

Эффективный маркетинг с Calltouch

• Анализируйте воронку продаж от показов рекламы до ROI от 990 рублей в месяц
• Отслеживайте звонки на сайте с точностью определения источника рекламы выше 96%
• Повышайте конверсию сайта на 30% с помощью умного обратного звонка
• Оптимизируйте свой маркетинг с помощью подробных отчетов: дашборды, графики, диаграммы
• Добавьте интеграцию с CRM и другими сервисами: более 50 готовых решений
• Контролируйте расходы на маркетинг до копейки

Узнать подробнее

Зачем нужен API?

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

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

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

Почему разработчики используют API?

Есть как минимум еще 4 причины, объясняющие интерес программистов к API:

1. API упрощает и ускоряет создание новых продуктов. Разработчикам не приходится каждый раз изобретать велосипед. Можно взять API нейронной сети TenserFlow, к примеру, и внедрить в свое программное обеспечение, а не создавать собственную систему машинного обучения.
2. Как я уже отметил выше, программный интерфейс увеличивает безопасность разработки. С помощью него можно вынести ряд функций в отдельное приложение, сделав невозможным их некорректное использование. От человеческого фактора это тоже спасает.
3. API упрощает настройку связей между разными сервисами и программами. Интерфейс нивелирует необходимость в тесном сотрудничестве создателей различных приложений. Разработчики могут внедрять поддержку сторонних сервисов, вообще не контактируя с их создателями.
4. Наличие готовых интерфейсов позволяет сэкономить не только время и силы программистов, но и финансы, с которыми часто связано создание новых программных решений.

Как еще используют API?

Компания ArtJocker использует API Serpstat для постановки KPI SEO-специалистам. Система работает следующий образом:

1. Сначала собираем ключи конкурентов с минусами и получаем объем трафика.

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

Рассчитываем!

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

Эти показатели проверяются калькулятором KPI от ArtJocker на совместимость с общей картиной по сайту. руководителя отдела маркетинга, погрешность не более чем в 5–10%.

Примеры и схемы ответов

Ниже приведен пример ответа от SendGrid API. Их документация обеспечивает отображение Примера на одной вкладке:

А схема ответа на другой вкладке:

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

Swagger UI также предоставляет и пример значения и схему/модель. Например, в , который используется в практике SwaggerUI (которое будет приведено позже в курсе), можно увидеть различие между примером ответа и схемой ответа. Вот Пример значения:

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

Схема ответа содержит все возможные свойства, возвращаемые в ответе. Вот почему нужен и пример ответа, и схема ответа. Вот схема ответа для API Sunrise и Sunset Times:

Схема или модель обеспечивает следующее:

• Описание каждого свойства;
• Определение типа данных для каждого свойства;
• Является ли каждое свойство обязательным или необязательным.

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

Примеры API

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

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

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

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

Google Календарь

Те, кто использовал приложения-календари для iOS или Android, знают, что данные в них можно синхронизировать, подключив один из популярных сервисов: Apple iCal или Google Calendar. Обе компании предлагают разработчикам API, позволяющие подключить свой календарь напрямую к сторонним приложениям. Благодаря подобной интеграции люди могут использовать несколько разных программ со схожей функциональностью и иметь на руках актуальную информацию о всех своих делах.

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

Погодное приложение

Существующие погодные приложения (встроенные в операционную систему или сторонние из App Store или Google Play) получают информацию о погоде из сторонних источников.

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

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

Сервис по заказу авиабилетов

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

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

Кнопки авторизации

Наверняка вы видели на различных сайтах кнопки, позволяющие зарегистрироваться с помощью уже существующих аккаунтов на популярных площадках. Сейчас такие есть у Google, Facebook, Apple, Twitter, ВКонтакте и т.д. Набор доступных опций на конкретном ресурсе полностью зависит от его хозяев. Это тоже делается через API. Условная Apple создала набор защищенных функций, который можно с минимальными затратами подключить к своему проекту и предоставить пользователям доступ к удобному и безопасному способу авторизации.

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

Навигация на сайтах и в приложениях

Тут почти как с погодой. Есть несколько крупных корпораций, предлагающих картографические данные. Те же Apple, Google, Yandex и парочка других. Некоторые из этих компаний разработали API, позволяющие подключить собственный картографический сервис к другим площадкам. Иногда они используются во внутренних продуктах. Яндекс.Транспорт построен на базе Яндекс.Карт, к примеру. Иногда API используются крупными партнерами. Uber использует для навигации сервис компании Google.

То же самое делают разработчики многих приложений под Android. Так как это API, встроенный в операционную систему, подключить карты Google к своему сервису доставки еды или приложению для бегунов проще всего. На iOS ситуация иная – там проще работать с Apple Maps.

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

Что такое API простыми словами

Данный термин можно расшифровать как Application Programming Interface, то есть Программный Интерфейс Приложения. Если вы часто взаимодействуете с компьютерами, то отлично знаете эту аббревиатуру, ведь это один из самых популярных околокомпьютерных терминов нашего времени. Но знаете ли вы что-нибудь кроме его расшифровки? Часто пользователи отвечают, что это некие инструменты для некого взаимодействия между программами, но на обычно этом знания заканчиваются.

Если уже не для чайников, то действительно – api состоит из функций, классов, методов и структур, которые помогают взаимодействовать одним программам с другими. В программный интерфейс включены своего рода «мосты», предоставляющие возможность приложению 1 связаться с приложением 2, чтобы получить от него данные или даже некоторые функции. Используя подобный интерфейс, программисты расширяют функциональность своего приложения и даже связывают его с продуктами других разработчиков – вот что такое api.

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