Api

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

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

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

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

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

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

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

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

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

Зачем нужен API

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

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

Перечислим основные причины интереса программистов к применению API:

• Программный интерфейс дает инструментарий для работы с ПО. Например, OpenAl помогает работать со звуковыми библиотеками в приложениях. Экономит время для разработчиков — не нужно писать звуковое ПО. 
• Связывает системы. С помощью API можно авторизоваться на сайте, используя аккаунт стороннего сервиса (Google, Facebook). По такому же принципу работают платежные системы, соединяясь с банковскими аккаунтами.
• Обеспечивает безопасность данных. Программный интерфейс выделяет данные, которые необходимо защищать. Таким образом, другие программы не смогут ими воспользоваться, если у них на это нет разрешения.
• Снижают стоимость программного продукта. Выгоднее пользоваться API, чем создавать ПО с нуля. 

Популярные API

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

• Facebook API позволяет логиниться на сторонних платформах с помощью своего аккаунта, оплачивать покупки в приложении, получать доступ к данным крупных и средних аккаунтов Instagram Business, управлять страницами сообществ и публиковать на них контент, получать статистику по рекламе, управлять объявлениями и аудиторией, запускать прямые эфиры,
• С помощью Twitter API можно показывать ленту твитов на сайте, управлять профилем и настройками учетной записи, автоматически создавать рекламные кампании в Твиттере и управлять ими,
• API ВКонтакте дает возможность отслеживать активность пользователей в сообществах, создавать ботов, собирать статистику по действиям в сообществе, автоматически модерировать контент, автоматизировать работу с товарами (например, импорт из внешней базы), получать текстовые публикации из ВКонтакте по заданным ключевым словам и т.д.,
• Telegram Bot API представляет собой HTTP-интерфейс для работы с ботами в Telegram,
• YouTube API позволяет встраивать видео на сайт, создавать плейлисты, встраивать плеер в приложение, получать данные об активности пользователей.

Не менее популярны и следующие API:

Яндекс API – у всех популярных сервисов Яндекса есть свои API (Вебмастер, Метрика, Директ, Маркет, Аудитории, Карты и т.д.), благодаря которым можно:

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

Google API

• Работа с устройствами и приложениями на платформе Android,
• Управление событиями в Календаре,
• Управление товарами и акккаунтом в Google Покупках,
• Управление файлами на Google Диске, включая загрузку, скачивание, поиск, изменение прав доступа,
• Просмотр и управление данными Google Analytics,
• Чтение и редактирование файлов в Документах,

Endpoint

Адрес, на который посылаются сообщения называется Endpoint.
Обычно это URL (например, название сайта) и порт. Если я хочу создать веб сервис
на порту 8080 Endpoint будет выглядеть так:

Если моему Web сервису нужно будет отвечать на различные сообщения я
создам сразу несколько URL (interfaces) по которым к сервису можно будет обратиться.
Например

Как видите у моих эндпойнтов (Enpoints) различные окончания. Такое окончание в Endpoint
называются Resource, а начало
Base URL.

Такое определение Endpoint и Resource используется, например, в

SOAP UI

для RESTful интерфейсов
https://andreyolegovich.ru:8080 — это Base URL
/resource1/status — это Resource

Endpoint = Base URL + Resource

Понятие Endpoint может использоваться в более широком смысле. Можно сказать, что
какой-то определённый роутер или компьютер является Endpoint. Например, в понятии
Endpoint Management под Endpoint
имеют в виду конечное устройство

Обычно это
понятно из контекста.

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

Термин Resource также связан с RESTful, но в более широком смысле может
означать что-то другое.

Набор функций в программных интерфейсах приложения

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

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

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

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

Внутреннее устройство API зависит от того, каким образом его организует разработчик. Есть стандартные варианты, но они не являются «догматом».

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

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

Как вызвать API?

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

Это может выглядеть так, например:

// Подключаем API
import SomeKindOfAPI
// Задействуем его на той или иной информации
let a = SomeKindOfAPI(SomeData)
// Возвращаем получившееся значение
return a

А вот как выглядит запрос к API Yandex.SpeechKit (для озвучки текста):

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

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

Но не только разработчики участвуют во взаимодействии с API. Пользователи тоже зачастую обращаются к интерфейсам. Банальная кнопка «Создать новую вкладку» в браузере – уже интерфейс (конкретно в этом случае – графический интерфейс). За ним так же скрывается набор функций, выполнение которых в конечном итоге приводит к появлению новой страницы в браузере.

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

API везде!

• По оценкам экспертов, к концу десятилетия пользователям будет доступно более 1 миллиона публичных API
• По статистике, более 9 миллионов разработчиков вовлечены в создание внутренних API. Сегодня фокус сдвигается в сторону разработки публичных API
• Интернет вещей (IoT) достигнет 20 миллиардов подключенных устройств к 2020 году
• в 2016 году заплатила 625 млн. долл. за покупку поставщика платформы управления API фирмы Apigee.
• Как рассказал руководитель центра консалтинга Aplana Амелин Владимир, в 2016 году число опубликованных Public API во всем мире достигло 16 тыс., а к 2020 г. их будет уже более 1 млн. В России их предоставляют «Яндекс», Mail.ru, «», «», в финансовой сфере — Сбербанк, ФК «Открытие», «Тинькофф Банк», ВТБ, а также крупные розничные сети, сервисы госуслуг и открытого правительства. Согласно проведенному опросу, 26% отечественных банков разработали или разрабатывают собственные API, еще 38% планируют сделать это в следующем году. По данным Gartner, 75% банков из мирового списка Top 50 уже имеют собственные открытые API, а к 2018 г. регуляторы половины стран G20 примут стандарты, регулирующие их применение. Разновидностью Public API являются интерфейсы категории Open API, базирующиеся на открытых стандартах и доступные широкому кругу разработчиков, как правило, на бесплатной основе. По словам Владимира Амелина, рост их популярности связан с тем, что все больше компаний видят в них потенциал для развертывания новых бизнес-моделей и понимают, как такие модели монетизировать.

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

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

Paypal

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

Начало работы в Твиттер

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

Parse Server

Начало работы Parse Server

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

Adsense

Начало работы Adsense

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

Aeris

Начало работы Aeris

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

Watson and IBM Cloud

Начало работы Watson and IBM Cloud

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

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

Организация курса

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

Используем REST API в роли разработчикаРоль разработчика поможет лучше понять потребности разработчиков, а также то, что разработчики обычно ищут в документации API. Разработчики часто используют такие инструменты, как Postman или curl, для совершения запросов. Они смотрят на структуру ответа и динамически интегрируют необходимую информацию в веб-страницы и другие приложения.

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

Спецификация OpenAPI и SwaggerСпецификация OpenAPI предоставляет один из способов описания REST API и включает все разделы, упомянутые в модуле Документирование конечных точек API. Фреймворки, такие как Swagger UI, могут анализировать спецификацию OpenAPI и генерировать интерактивную документацию, которая позволяет пользователям опробовать конечные точки при изучении API.

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

Однако простая игра в редакционную/издательскую функцию может сделать из вас простого секретаря.

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

Вы можете оценить качество документации API, посмотрев, включает ли она эти не справочные темы.

Публикация документации APIДокументация по API часто соответствует принципу docs-as-code, где инструменты для создания и публикации документации тесно связаны с теми же инструментами, которые разработчики используют для написания, управления, построения и развертывания кода. Docs-as-code включает в себя использование облегченных форматов разметки, таких как Markdown, совместную работу с помощью Git или других систем управления версиями, создание сайта документации с помощью генератора статического сайта и развертывание его с помощью модели непрерывной сборки, где сборка происходит на сервере при фиксировании изменений в определенной ветви.

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

Нативные библиотеки APIAPI нативных библиотек относятся к Java, C ++ или другим API, специфичным для программирования. При таком подходе вместо запроса информации через Интернет, библиотека кода загружается и интегрируется в проект. Библиотека компилируется непосредственно в сборку приложения (а не доступна через веб-протоколы, как с REST API). Хотя такой тип API встречается реже, он включен здесь частично, для пояснения, что отличает API REST от API нативных библиотек.

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

API операционных систем. Проблемы, связанные с многообразием API

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

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

С другой стороны, отличия в API различных операционных систем существенно затрудняют перенос приложений между платформами. Существуют различные методы обхода этой сложности — написание «промежуточных» API (API графических интерфейсов Qt, Gtk, и т. п.), написание библиотек, которые отображают системные вызовы одной ОС в системные вызовы другой ОС (такие среды исполнения, как Wine, cygwin, и т. п.), введение стандартов кодирования в языках программирования (например, стандартная библиотека [[Си языка C), написания интерпретируемых языков, реализуемых на разных платформах (sh, perl, php, tcl, Java, и т. д.)

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

Например: для того, чтобы увидеть в браузере строчку «Hello, world!» достаточно лишь создать HTML-документ с минимальным заголовком, и простейшим телом, содержащим данную строку. Что произойдёт, когда браузер откроет этот документ? Программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл, и разберётся в его устройстве, повызывает через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать выбранным шрифтом Hello, world!», при этих операциях библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы с запросами вида «а положи-ка мне в буфер видеокарты вот это».

При этом практически на каждом из уровней реально существует несколько возможных альтернативных API. Например: мы могли бы писать исходный документ не на HTML, а на LaTeX, для отображения могли бы использовать любой браузер. Различные браузеры, вообще говоря, используют различные HTML-библиотеки, и, кроме того, всё это может быть (вообще говоря) собрано с использованием различных библиотек примитивов и на различных операционных системах.

Основными сложностями существующих многоуровневых систем API, таким образом, являются:

• Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
• Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.

Особенности современного API

В развитии программных интерфейсов наблюдаются следующие тенденции:

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

От практики до документации

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

Как технические писатели, будем рассматривать каждый элемент в документации API:

1. Описание ресурса
2. Конечная точка и методы
3. Параметры
4. Пример запроса
5. Пример ответа

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

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

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

API7:2019 Security Misconfiguration (Некорректная настройка параметров безопасности)

• Используются дефолтные настройки приложений, которые могут быть небезопасны.
• Используются открытые хранилища данных.
• В OpenSourсe попала закрытая информация, например, конфигурация системы или параметры доступа.
• Неправильно сконфигурированы HTTP заголовки (данная тема рассмотрена далее в разделе «Insecure HTTP Headers»).
• Аутентификационные данные (логин/пароль, токен, apiKey) посылаются в URL. Это небезопасно, т.к. параметры из URL могут оставаться в логах веб серверов.
• Отсутствует или неправильно используется политика Cross-Origin Resource Sharing (CORS) (данная политика рассмотрена далее в одноимённом разделе).
• Не используется HTTPS (использование HTTPS рассмотрено в разделе «Insecure Transport»).
• При эксплуатации промышленной системы используются настройки, предназначенные для разработки и отладки.
• Сообщения об ошибках содержат чувствительную информацию, например, трейсы стека.

• Для пользователей устанавливать только необходимые права доступа.
• Открывать только необходимые сетевые порты.
• Устанавливать безопасные версии патчей OS и приложений (подробно рекомендации рассмотрены в разделе «Using Components with Known Vulnerabilities»).