17 интересных (и забавных) api для вашего проекта

Примеры API в нашей жизни

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

Заказ авиабилетов. Многие пользуются агрегаторами билетов, такими как Aviasales и SkyScanner. Такие сервисы собирают информацию о стоимости авиабилетов в разных авиакомпаниях и отображают ее в едином окне. Это позволяет реализовать API, встроенный в сайты авиакомпаний, который помогает в реальном времени обновлять информацию о направлениях и стоимости.

Поиск авиабилета на Aviasales

Навигация на сайтах и в приложениях. Крупные компании, в том числе Apple, Google, «Яндекс» и другие, разработали API, позволяющие подключить собственный картографический сервис к другим площадкам. Так, в «Яндекс.Карты» встроены сервисы «Транспорт» и «Пробки». Многие приложения на Android, например, по доставке еды или для спорта, используют встроенный в ОС API, чтобы подключить карты Google к своему сервису. На iOS аналогичная ситуация с Apple Maps.

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

Как работает API?

Теперь, когда мы установили, что API — это набор процедур, которые указывают программное обеспечение в правильном направлении, как именно это все работает?

Лучший способ объяснить основные функциональные возможности API — это привести пример из реальной жизни. Службы доставки еды, такие как GrubHub , сейчас невероятно популярны, поэтому давайте обсудим, как может работать код таких мобильных приложений.

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

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

API — это связь между этой базой данных и веб-сайтом или приложением, которое представляет свои данные

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

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

API — это интерфейс, отвечающий за доставку данных из базы данных в приложение, будь то веб-сайт, мобильное приложение или что-либо еще. 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.

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

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

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

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

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

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

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

Зачем нужен API

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

Дело в том, что api помогает ещё в двух невероятно важных процессах:

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

Тестирование 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 в других программах, что является стандартной практикой.

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

Сделано это для того, чтобы сторонние программы могли:

• Взаимодействовать с файловой системой;
• Создавать графику;
• Сохранять и хранить важные данные;
• Пользоваться сетевыми возможностями;
• Запускать видео, аудио и другое.

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

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

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

Избегайте неатомарных операций

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

Плохо:

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

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

Лучше:

Здесь:

• — уникальный идентификатор каждого атомарного изменения;

• — время проведения каждого изменения;

• — информация по ошибке для каждого изменения, если она возникла.

Не лишним будет также:

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

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

Неатомарные изменения нежелательны ещё и потому, что вносят неопределённость в понятие идемпотентности, даже если каждое вложенное изменение идемпотентно. Рассмотрим такой пример:

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

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

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

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

Что будет, если API отключится или поменяются условия

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

Раньше было так: есть открытый API для карт, им можно было пользоваться почти без ограничений — 750 000 бесплатных запросов, этого хватало почти для каждой компании. Программист просто формировал специальный код для вставки на сайт, который обращался к серверу Гугла и получал в ответ нужный кусок карты со всеми функциями. Получается, что в каждом таком сайте была встроена мини-версия сервиса Google Maps.

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

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

Бензиновые двигатели API S_

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

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

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

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

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

G – 1989 год – это классика в российском автопроме (ВАЗ 2106/07/08/09 и т.д), поэтому, вполне вероятно, что у кого-то в гараже еще есть 28 летняя старушка, которая, благодаря бережному отношению хозяина еще на ходу. Так вот моторные масла отмеченные буквой G – это то, что Вам нужно. Данные масла уже обладают такими полезными свойствами, как защита двигателя от ржавчины.

H —  эта улучшенная версия моторного масла предназначена для бензинового двигателя, разработанного по технологии 1994 года выпуска. Здесь уже начали появляться такие присадки, которые более-менее защищают двигатель от износа и загрязнений + данные масла противостоят коррозии.

 J – продукт, который предназначен для всех видов транспортных средств чей ДВС был улучшен в 1996 году. В маслах данной категории появляется новое преимущество – они способствуют защите двигателя при минусовых температурах. То есть впервые в 1996 году появилось масло, которое хоть как-то могло завести двигатель в мороз.

L – 2000год, появляется первое масло, которое можно назвать экологически чистым. Таким образом, все автомобили, произведенные в 2000году и позднее, нуждаются именно в данном продукте, дабы соблюдать экологические мировые нормы. Данное масло уже можно заливать в турбированные и инжекторные авто.

M —  одно из последних и современных поколений моторных масел, которые подходят для современных автомобилей. Данная классификация существует с 2004 года и соответственно подходит для авто не старше 13 лет (на момент 2017 года). Масла, которые в результате проверки получили данную категорию, соответствуют требованиям по защите двигателя от загрязнений и износа. Таким образом, они обеспечивают качественную работу современных ДВС. Также масла данной категории полностью адаптированы к любым погодным условиям и в зависимости от вязкости могут сохранять свои характеристики как при -35, так и при +40 .

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

Избегайте неявного приведения типов

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

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

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

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

Хорошо

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

Плохо:

Хорошо

NB: противоречие с предыдущим советом состоит в том, что мы специально ввели отрицающий флаг («нет лимита»), который по правилу двойных отрицаний пришлось переименовать в . Хотя это и хорошее название для отрицательного флага, семантика его довольно неочевидна, разработчикам придётся как минимум покопаться в документации. Таков путь.

Преимущество API

Использование API имеет ряд преимуществ.

Мы не нашли весь их список в алфавитном порядке и поэтому выделили несколько самых важных:

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

API, использующие протокол HTTP = веб-сервисы

«Веб-сервис» — это веб-приложение, предоставляющее ресурсы в формате, используемом другими компьютерами. Веб-сервисы включают в себя различные типы API, в том числе REST и SOAP API. Веб-сервисы — это, в основном, запросы и ответы между клиентами и серверами (компьютер запрашивает ресурс, а веб-сервис отвечает на запрос).

API, использующие протокол HTTP для передачи запросов и ответов, рассматриваются как «веб-сервисы». В случае веб-сервисов клиент, делающий запрос на ресурс, и сервер API, предоставляющий ответ, могут использовать любой язык программирования или платформу. Не имеет значения, какой ЯП или платформа будут использоваться, потому что запрос сообщения и ответ сделаны через общий веб-протокол HTTP.

Веб-протокол является частью прекрасного веб-сервисов: они независимы от языка и поэтому совместимы между различными платформами и системами. При документировании REST API не имеет значения, строят ли инженеры API с помощью Java, Ruby, Python или какого-либо другого языка. Запросы выполняются через HTTP, и ответы возвращаются через HTTP.

Диаграмма ниже показывает общую модель REST API:

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

Любой язык программирования, создающий запрос, будет по-своему отправлять веб-запрос и анализировать ответ на своем языке. Эти специфичные для языка функции отправки запросов и анализа ответов не являются частью REST API (хотя они могут быть предоставлены в прилагаемом SDK). REST API не зависит от языка и обрабатывает входящую и исходящую информацию по HTTP.

SDK представляют инструменты для API

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

Например, в одной компании был и REST API, и JavaScript SDK. Поскольку JavaScript был целевым языком, над которым работали разработчики, компания разработала SDK JavaScript, чтобы упростить работу с REST с использованием JavaScript. Стало возможным отправлять вызовы REST через JavaScript SDK, передавая ряд параметров, относящихся к веб-дизайнерам.

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