Почему использование API в вашем коде похоже на игру с LEGO.

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

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

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

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

• getLikeCount()
• createGoogleSheet()
• sendEmail()

Откуда мы знаем, что это за «фрагменты кода»?

Каждый API поставляется с документацией , в которой перечислены все способы его использования, что-то вроде каталога LEGO. Он показывает вам все, что вы можете сделать с помощью API, что для Reddit API может быть «опубликовать комментарий» или «сохранить публикацию». Документацию часто можно найти в Интернете на веб-сайте компании, обычно на какой-нибудь скрытой странице разработчика. « Вещи, которые вы можете сделать», называются «методами API».

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

Самый простой API: получение вашего IP-адреса

Давайте посмотрим на API, который состоит только из одной части: API IPify , который сообщает вам, какой у вас IP-адрес.

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

Мы собираемся отправить одну команду на IPify.org и спросить, какой у нас IP-адрес. Это работает как на Mac OS, так и на Windows.

Откройте Терминал (Mac) или Командную строку (Windows) и введите следующее:

curl 'https://api.ipify.org?format=json'

      
                

                    
                    
                
            

{"ip": "68.142.10.250"}

Чтобы убедиться, что это ваш настоящий IP-адрес, посетите WhatIsMyIPAddress.com .

JSON — один из самых популярных форматов данных для современных веб-API. Он помещает все в {“key”: value}формат, так что все данные имеют метку. Другие API могут использовать XML , который имеет аналогичный <Key>value</Key>формат, и многие API позволяют выбирать между ними.

Это суть многих веб-API. Мы запрашиваем у веб-сайта некоторые данные, и он отвечает этими данными. API-интерфейсы, распространенные в научных исследованиях, такие как API-интерфейсы NASA , USGS и USFDA , работают таким образом. Мы можем получить данные о космических спутниках, высоте гор в США и списке одобренных FDA лекарств, если просто попросим об этом.

Как насчет автоматизации действий пользователей?

Что, если мы не хотим просто собирать данные с веб-сайта? Как насчет создания ботов или автоматизации нашего рабочего дня?

Здесь на помощь приходят более сложные API. Они по-прежнему включают отдельные команды, когда мы обращаемся к веб-сайту или приложению и говорим: «Я хочу получить эти данные (или отправить эти данные)». И приложение отвечает соответственно. Но теперь мы объединяем несколько команд для выполнения более сложных действий.

Многоэтапный пример: Reddit API

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

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

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

У нас есть повседневные взаимодействия с пользователем, такие как комментирование ( /api/comment), отслеживание и сохранение сообщений . API Reddit позволяет делать это с помощью кода. Префикс /api/для всех методов выглядит странно, но мы объясним это через минуту.

Google Search API , напротив, имеет только один метод поиска :

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

Это цель каждого API — свести все действия и параметры обычного веб-сайта или приложения к таким готовым к коду функциям «одного лайнера», которые мы можем использовать из Python, JavaScript, Bash, Java, R и т. д. .

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

Как использование API выглядит в коде

Итак, как это выглядит в коде? Reddit API говорит, что метод комментариев называется /api/comment. Что это значит? Мы не можем просто вставить /api/commentфайл Python и на этом закончить, верно? Верно.

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

Более подробно: веб-API в коде

Мы видели, что методы Reddit API перечислены с кучей косых черт:

Это совсем не похоже на Python, JavaScript или код. Это говорит /api/? Что это такое?

На самом деле это части HTTP-ссылок , точно такие же, как те, которые вы вводите в Chrome или Firefox.

Но почему веб-ссылки? Помещаем ли мы их прямо в наш код? Да, и не зря.

Когда мы используем веб-API, такой как Reddit, Gmail или даже API-интерфейсы NIH или NASA , наш код в основном общается с веб-сайтом. Веб-сайты используют links/that/look/like/thisдля разделения своих страниц и функций. Google живет в google.com, но результаты поиска живут в google.com/search.

В итоге мы поместим эту конечную точку в наш код примерно так:

google_search_api = "https://www.googleapis.com/customsearch/"

Теперь код на самом деле общается не с веб-сайтом, а с сервером (например, безголовым веб-сайтом), но они организуют то же самое с /slashes/, что касается API. Точно так же, как когда вы публикуете блог как обычный пользователь на веб-сайте со страницы website.com/post, ваш код может обращаться к конечной точке публикации блога сервера API по api.website.com/postадресу website.com/api/postи т.п.

Подумайте об этом так: когда вы проверяете свой почтовый ящик Gmail на своем ноутбуке или телефоне, ваш браузер:

1. Обратитесь через Интернет, чтобыgmail.com
2. Скажите gmail.com: «Могу ли я разместить веб-страницу под /mail/inbox?»
3. Затем Gmail отправляет веб-страницу для вашего почтового ящика обратно в ваш браузер, чтобы вы могли ее увидеть.

1. Протянуть рукуgmail.googleapis.com
2. Спросите gmail.googleapis.comсвой почтовый ящик
3. Тогда API Gmail отправит обратно только данные, а не весь сайт.

Чистые данные удобны для кода, и именно для этого созданы API.

Пример: Получение лекарств через API openFDA

Вот краткий пример Python для запроса API openFDA USFDA , в котором перечислены все лекарства, одобренные FDA:

# import an HTTP library
import requests

# Tell "requests" to request data from the openFDA "Drugs" endpoint
drugs_http_endpoint = "https://api.fda.gov/drug/label.json?limit=100"
drugs = requests.get(drugs_http_endpoint)

# Print all the data that we got from USFDA about drugs
print(drugs.json())

Примечание: в приведенном выше примере используется популярная requests библиотека HTTP для Python.

Как насчет API для Bluetooth и носимых устройств?

Использование API носимых устройств (таких как Fitbit или Apple Watch) немного отличается от использования API веб-сайта, но они задокументированы одинаково. Например, вместо метода «комментарий» носимый API может иметь следующие методы:

• узнать частоту сердечных сокращений
• получить данные о движении (от акселерометра и гироскопа)
• отправить пользователю оповещение

Пример носимого устройства: API Fitbit

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

API Fitbit состоит из нескольких частей . У него даже есть собственный веб-API.

Давайте рассмотрим одну из частей Device API .

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

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

• чтение или установка часов
• чтение акселерометра (часть трекера движения)
• чтение пульсометра и т. д.

Информации много, но на странице есть краткий пример сценария, а затем перечислено множество деталей LEGO, связанных с сердечным ритмом, которые мы можем использовать в нашем собственном коде:

• activated(сообщает нам, включен датчик сердечного ритма или нет)
• heartRate(сообщает нам текущую частоту сердечных сокращений)
• onactivate(функция, которую мы можем использовать, чтобы сообщить Fitbit, что делать, как только активируется датчик сердечного ритма)

В псевдокоде это означает:

import HeartRateSensor code from Fitbit's API

if HeartRateSensor was imported {
    hrm = the HeartRateSensor
    
    Listen for heart rate sensor to send data, then print it.

    Start the heart rate sensor (which will then start the above "Listen" code)
}

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

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

Краткое содержание

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

Если у вас есть какие-либо вопросы или отзывы, напишите нам по адресу [email protected] или напишите нам в Instagram (@protobioengineering) . Спасибо за прочтение.

Ссылки по теме

• GitHub для биологов
• Dataverse API: исследовательские данные и программное обеспечение с открытым исходным кодом
• Почтальон: создание и тестирование API