Api

Введение

Вы наверное безумец, если не согласны со следующим утверждением:

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

Однако, вам кажется, что вы не совсем понимаете что это такое.

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

Не беспокойтесь! Эта статья – то, чего вы так долго ждали!

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

К концу прочтения статьи вы будете знатоком этой темы!

Хватит вступлений. Начнем, пожалуй!

Работа с запросами и отправка запросов в Postman

У Postman есть графический интерфейс, что выгодно отличает его от ряда других инструментов тестирования. Чтобы создать запрос, нужно нажать на кнопку New и выбрать пункт Request. 

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

Создадим запрос на получение проектов. Назовём его соответственно: /api/v2/projects 

По умолчанию открывается форма создания GET-запроса:

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

1. Выбираем тип запроса. Postman предлагает внушительный список, нам нужен GET.

2. Указываем URL запроса. Первая часть ссылки должна содержать адрес сервера, где развёрнута наша TMC. Мы используем публичное API Test IT, а при составлении запросов опираемся на Swagger-документацию. В нашем случае полная ссылка будет выглядеть так: https://testit.geekbrains.ru/api/v2/projects. 

3. На вкладке параметров указываем ключи и значения запроса. Мы хотим получить только удалённые проекты, и API Test IT предоставляет нам такую возможность. Укажем в параметрах isDeleted=true.

4. Переходим на вкладку Authorization, указываем данные для идентификации пользователя. Postman поддерживает множество типов авторизации, параметры для каждого из них отличаются. Используем авторизацию по API Key, полученному из личного кабинета в Test IT.

Мы заполнили все необходимые данные. Теперь выполним запрос, нажав кнопку Send.

Видим, что запрос прошёл успешно: код 200, тело ответа, время ответа и сколько занимают полученные данные. Правда, в нашем случае тело ответа будет пустое, поскольку удалённых проектов у нас нет. Советуем в ключ isDeleted ставить значение true.

Отправляемый запрос или ответ мы можем сохранить с помощью меню справа:

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

Как было сказано ранее в разделе Что такое 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

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

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

Также есть и Web API.

Самые известные типы API:

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

Все еще недостаточно?

Больше примеров?

Подумайте о Windows, компьютерной операционной системе, разработанной Microsoft для работы с ПК (персональными компьютерами).

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

Более того, Windows – не единственная операционка, которая предоставляет API. Большинство ОС это делают.

Какая цель?

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

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

Встраивание динамических ответов

Иногда ответы генерируются динамически на основе вызовов API в тестовой системе. Например, посмотрите на API Rhapsody и щелкните конечную точку — ответ генерируется динамически.

Другой API с динамическими ответами — это API OpenWeatherMap (с которым мы практиковались ранее). Если щелкнуть ссылку в разделе «Примеры вызовов API», например http://samples.openweathermap.org/data/2.5/weather?q=London, вы увидите ответ, возвращенный в браузере.

На самом деле, ответ OpenWeatherMap не генерируется динамически, но он так выглядит.

API Citygrid, который мы рассмотрели в разделе Пример запроса, также динамически генерирует ответы.

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

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

Ниже приведены несколько примеров разделов “Начало работы” в 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.

Плюсы и минусы работы с API

Плюсов у использования API немало:

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

Но также есть и минусы:

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

Избегайте частичных обновлений

Плохо:

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

Во-первых, экономия объёма ответа в современных условиях требуется редко. Максимальные размеры сетевых пакетов (MTU, Maximum Transmission Unit) в настоящее время составляют более килобайта; пытаться экономить на размере ответа, пока он не превышает килобайт — попросту бессмысленная трата времени.

Перерасход трафика возникает, если:

• не предусмотрен постраничный перебор данных;

• не предусмотрены ограничения на размер значений полей;

• передаются бинарные данные (графика, аудио, видео и т.д.).

Во всех трёх случаях передача части полей в лучше случае замаскирует проблему, но не решит. Более оправдан следующий подход:

• для «тяжёлых» данных сделать отдельные эндпойнты;

• ввести пагинацию и лимитирование значений полей;

• на всём остальном не пытаться экономить.

Во-вторых, экономия размера ответа выйдет боком как раз при совместном редактировании: один клиент не будет видеть, какие изменения внёс другой. Вообще в 9 случаях из 10 (а фактически — всегда, когда размер ответа не оказывает значительного влияния на производительность) во всех отношениях лучше из любой модифицирующей операции возвращать полное состояние сущности в том же формате, что и из операции доступа на чтение.

В-третьих, этот подход может как-то работать при необходимость перезаписать поле. Но что делать, если поле требуется сбросить к значению по умолчанию? Например, как удалить ?

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

Хорошо: можно применить одну из двух стратегий.

Вариант 1: разделение эндпойнтов. Редактируемые поля группируются и выносятся в отдельный эндпойнт. Этот подход также хорошо согласуется , который мы рассматривали в предыдущем разделе.

Теперь для удаления достаточно не передавать его в . Этот подход также позволяет отделить неизменяемые и вычисляемые поля ( и ) от изменяемых, не создавая двусмысленных ситуаций (что произойдёт, если клиент попытается изменить ?). В этом подходе также можно в ответах операций возвращать объект заказа целиком (однако следует использовать какую-то конвенцию именования).

Вариант 2: разработать формат описания атомарных изменений.

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

Кто разрабатывает API-платформы и как они работают

Согласно вышеупомянутому «волшебному квадранту» агентства Gartner, лидерами на рынке систем управления полным жизненным циклом API являются компании Google, CA Technologies, IBM, Software AG, MuleSoft, Red Hat и TIBCO Software. Агентство Forrester в своем недавнем исследовании называет лидерами компании IBM, Google, Software AG, Rogue Wave Software и WSO2.

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

Интерфейс администрирования API

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

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

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

Наконец, пять лет назад мы представили полный жизненный цикл управления API в рамках платформы управления API webMethods. В 2014 г. мы запустили webMethods API Portal для разработчиков API, а в 2016 г. объединили функционал API-шлюз webMethods API Gateway, портала и средств медиации и управления жизненным циклом в одну платформу. Эти средства поддерживают разработку API, их сборку, одобрение и публикацию в принятом технологическом стандарте и являются частью платформы Software AG Hybrid Integration & API.

Выбор спецификации API

Разработка web API

Перевод

Интро

Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.
В тексте попадаются комментарии переводчика, они выделены курсивом.

Понятные URL для вызовов API

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

Что было до API?

API существовал не всегда. Его появление на рынке стало технологической революцией и внесло много изменений в онлайн мир.

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

В чем была проблема?

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

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

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

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

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

Пример того, как используется API:

Знаете, почему вы можете быстро зарегистрироваться в разных приложениях, используя только аккаунт Facebook?

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

Что будет, если не использовать API?

Если вы решите не использовать API, приложение может, например, узнать о новой статье Академии Mobidea открыв www.academy.mobidea.com

Затем приложение прочтет веб страницу, как если бы оно было человеком, и интерпретирует контент страницы, в данном случае – Академии.

Та же ситуация с использованием API: приложение находит информацию о веб странице www.academy.mobidea.com , отправив сообщение на API Академии Mobidea.

Сообщение отправляется в формате JSON.

Что такое формат JSON?

Формат JSON (JavaScript Object Notation) это файл открытого стандарта, содержащий объекты данных и соответствующие атрибуты.

Например, когда мы проверяем новые статьи в Академии Mobidea, передаваемый JSON файл выглядел бы так:

article {

title: “Новая статья”,

date: 01/01/2017,

content: “Много текста.”,

author: “Джон Уайт”

}

Далее, после отправки сообщения в формате JSON, API страницы www.academy.mobidea.com реагирует структурированным ответом, похожим на пример выше.

Почему метод передачи информации так важен?

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

Это значит, что информация остается неизменной, вне зависимости от того, меняет ли веб страница свой внешний вид и дизайн или нет.

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

Что случится, если сайт поменяется, и при этом API не был использован?

Скорее всего приложение перестанет работать!

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

Оно просто не сможет понять данные, передаваемые с данного вебсайта.

В итоге, API это более безопасный и надежный вариант.

С ним вы можете быть уверены в том, что приложение продолжит работать с сайтом.

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

9 трендов развития унифицированных коммуникаций в 2021 году

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

Глобальное внедрение UCaaS

Один из главных трендов UC — рост популярности UCaaS. Крупные компании делают инвестиции в унифицированные коммуникации как в готовую систему бизнес-коммуникаций. Это связано с тем, что UCaaS объединяет в облаке основные каналы и платформы связи (голос, видео, чат, электронную почту и пр.). По мнению экспертов, к 2024 году рынок UCaaS будет оцениваться примерно в $79 млрд.

Тяжкое наследие прошлого. Проблемы командной строки Windows

Перевод

Предисловие от автора, Рича Тёрнера из Microsoft. Это статья о командной строке: от её появления и эволюции до планов капитального ремонта Windows Console и командной строки в будущих версиях Windows. Будь вы опытным профессионалом или новичком в IT, надеемся, что вы найдёте статью интересной.

Давным-давно в далёкой-далёкой серверной…

С первых дней развития информатики людям нужен был эффективный способ передавать компьютеру команды и данные и видеть результат выполнения этих команд/вычислений.
Одним из первых по-настоящему эффективных человеко-машинных интерфейсов стал Tele-Typewriter или «телетайп». Это электромеханическая машина с клавиатурой для ввода данных и каким-нибудь устройством вывода — сначала использовался принтер, позже экран.

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

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

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

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

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

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

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

Примеры API

Не так сложно найти примеры API.

Почему?

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

Гиганты технологий, такие как Twitter, YouTube и Facebook, например, все работают с API.

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

У разработчиков есть доступ к ключевым данным Twitter.

К тому же  поисковые API дают разработчикам методы для взаимодействия с данными трендов и поиском Twitter.

YouTube также использует API.

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

Вот некоторые из API YouTube:

YouTube Player API, YouTube Data API, YouTube Live Streaming API, YouTube Analytics API.

Как насчет Facebook? Как используется API в этом случае?

Заметьте, что вы можете оставлять Facebook комментарии на любом сайте и синхронизировать эти комментарии со страницей на Facebook.

API!

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

API позволяет пользователям оставлять комментарии в блоге.

Этот комментарий также появляется на Facebook странице, связанной с этим блогом. И это удобно всем!

Как сгруппировать несколько конечных точек одного ресурса

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

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

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

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

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