Чтобы разные программы могли общаться друг с другом, используют API — специальные наборы правил и инструментов. Представим, что одна программа пришла в кафе. Чтобы сделать заказ, программа выбирает какие-то позиции в меню и перечисляет их официанту. Официант — это API, который принимает заказ, передаёт его на кухню, то есть другой программе-повару, а затем приносит первой программе то, что она заказала.
Получается, что API — что-то вроде универсального переводчика, который помогает программам обмениваться данными и функциями. Достаточно добавить в код несколько функций с нужными запросами, и тогда, например, приложение погоды на смартфоне будет запрашивать данные у сервера метеорологических данных, а затем показывать пользователю соответствующий прогноз.
Бывает, что нужно убедиться, что API работает как надо и передаёт то, что нужно. Чтобы не проверять всё на настоящей программе, делают проще и тестируют API с помощью отдельных инструментов. Рассказываем о некоторых из них.
curl
Curl (расшифровывается как Client URL Request Library) — инструмент командной строки для передачи данных. Проверить установку можно командой curl --version. Если всё установлено правильно, вы увидите краткую информацию о версии программы:
Иногда в документации к API приведены шаблоны запросов через curl, но если их нет, можно использовать реальные GET-запросы. Для этого перед запросом в командной строке нужно написать curl. Например, мы хотим получить случайное аниме из базы данных MyAnimeList, у которой есть Jikan API. Если бы это случайное аниме запрашивала программа, она бы использовала команду GET "https://api.jikan.moe/v4/random/anime". В нашем случае проверки с помощью curl эта команда будет выглядеть так:
curl https://api.jikan.moe/v4/random/anime
Отправляем запрос и смотрим на ответ. Разобрать его сложно:
Чтобы содержание можно было понять, нам понадобится ещё одна утилита для командной строки — jq. Установить нужную версию для своей системы можно на официальном сайте.
После установки нужно добавить в конце запроса | jq:
curl https://api.jikan.moe/v4/random/anime | jq
Теперь ответ разобрать гораздо проще:
Некоторые сервисы специально адаптированы для работы с curl. Например, попробуйте отправить запрос curl wttr.in и посмотреть на результат.
Postman
Postman — одна из самых популярных утилит для тестирования API. Можно скачать десктопную версию, пользоваться веб-приложением или установить плагин для среды разработки Visual Studio Code. У Postman есть платная версия, но для большинства задач тестирования достаточно бесплатной.
Чтобы начать пользоваться веб-приложением, нужно создать аккаунт на postman.com. Плагин для VS Code находим в разделе расширений:
Для работы с Postman понадобится создать проект. Для этого переходим на вкладку Workspaces:
И добавляем новый нажатием на кнопку Create Workspace:
В некоторых API-документациях есть опция — запустить сразу в Postman. Например, такая кнопка есть у SpaceX API:
После перехода на другую страницу сервис спросит, в какой версии мы хотим работать с API:
При переходе из документации API на одну из версий Postman попросит выбрать, в какой из существующих проектов импортировать API, который мы хотим протестировать. В онлайн-версии это будет выглядеть так:
Теперь в панели слева у нас разделены по папкам все варианты запросов, которые можно отправить в SpaceX: информация про капсулы, запуски, технику, экипаж. Не знаем, насколько эти данные соответствуют реальности, но звучит круто:
Когда мы выбираем один из вариантов запроса, он автоматически подставляется в рабочее окно. Например, если выберем папку Rockets → запрос Get all Rockets и нажмём синюю кнопку Send, то получим JSON на 460 строк с информацией о ракетах:
Python
Python — или любой другой язык программирования — ещё один вариант протестировать работу API. Если вы пишете своё приложение и хотите добавить программный интерфейс для работы с другим сервисом, этот способ удобнее всего.
Для отправки запросов в Python нужно добавить библиотеку с нужными функциями. Таких библиотек несколько, мы добавим requests. Сначала устанавливаем её командой pip install requests.
Это можно сделать в терминале:
…или прямо в IDE, в котором работаете:
Попробуем отправить запрос на Numbers API, используя шаблон кода из документации RapidAPI.
Сначала импортируем библиотеку:
# импортируем библиотеку в проект
import requestsТеперь возьмём URL-адрес из запроса для получения факта из математики и сохраним его в переменную:
# объявляем переменную с адресом, на который нужно послать запрос
url = "https://numbersapi.p.rapidapi.com/1729/math"По инструкции RapidAPI нам нужно добавить в запрос дополнительные параметры-заголовки. Один из них — это ваш личный токен, API-ключ. Посмотреть его можно здесь:
Мы для примера вставляем ненастоящий токен, поэтому, чтобы запрос сработал, в код ниже нужно будет вставить свой напротив ключа "x-rapidapi-key".
# добавляем в запрос заголовки — личный API-ключ и хост, который принимает запросы
headers = {
"x-rapidapi-key": "cbas234jl2lkj23lj324lj3lj34j23ljs09sdf234jksdf0dsfs90fs70",
"x-rapidapi-host": "numbersapi.p.rapidapi.com"
}
После этого можно делать запрос. Чтобы сохранить данные, объявляем ещё одну переменную и добавляем в запрос URL-адрес и заголовки:
# объявляем переменную, в которую сохраним результат
# GET-запроса по заданному URL и нужные заголовки
response = requests.get(url, headers=headers)Чтобы увидеть результат, выведем запрос на экран в текстовом формате. Перед этим добавим проверку на статус-код ответа от сервера. Если код равен 200, можно выводить текст ответа. Если сервер вернул другой код, выведем код ошибки:
# если от сервера пришёл статус-код успешного запроса,
# выводим на экран ответ в формате текста
if response.status_code == 200:
print(response.text)
# если от сервера пришёл статус-код ошибки запроса,
# выводим на экран этот статус-код
else:
print(f"Запрос не удался. Код ошибки: {response.status_code}")Если запустить этот код целиком с нашим настоящим API-ключом, придёт такой ответ:
1729 is the smallest natural number representable in two different ways as a sum of two positive cubes, as Ramanujan stated on the spot.
Теперь попробуем подставить вместо 1729 неподходящий формат — напишем abcd:
# объявляем переменную с адресом, на который нужно послать запрос
url = "https://numbersapi.p.rapidapi.com/abcd/math"Получим ошибку, потому что тип значений в этом поле должен быть целым числом. В нашем сообщении об ошибке мы этого не увидим, потому что проверяем статус-код сервера. Нам придёт такое:
Запрос не удался. Код ошибки: 404
Как вывести отдельное значение из ответа
Иногда ответ приходит в виде огромного JSON-значения или списка, а нам нужно только что-то одно из всего этого массива. Для этого можно воспользоваться индексами и ключами.
Ответ от SpaceX API на запрос обо всех запусках приходит в виде списка. Мы достанем оттуда три конкретных факта: название запуска, дату и детали.
Сначала импортируем библиотеку и укажем адрес для запроса:
# импортируем библиотеку в проект
import requests
# создаём запрос по указанному в документации адресу
response = requests.get("https://api.spacexdata.com/v4/launches")Чтобы можно было извлекать данные по ключам, переводим ответ в формат JSON:
# переводим ответ в формат json
data = response.json()Теперь выделяем набор ключей по конкретному виду запуска. Мы в примере возьмём первый:
# выделяем информацию о первом запуске
latest_launch = data[1]Теперь берём эту информацию и сохраняем в каждую переменную значения по нужным ключам — launch_name, launch_date, launch_details. После этого выводим значения на экран:
# получаем значения по ключам: имя, дата запуска, детали
launch_name = latest_launch['name']
launch_date = latest_launch['date_utc']
launch_details = latest_launch['details']
# выводим каждое полученное значение отдельно
print('launch_name: ', launch_name)
print('launch_date: ', launch_date)
print('launch_details: ', launch_details)Запускаем:
launch_name: DemoSat
launch_date: 2007-03-21T01:10:00.000Z
launch_details: Successful first stage burn and transition to second stage, maximum altitude 289 km, Premature engine shutdown at T+7 min 30 s, Failed to reach orbit, Failed to recover first stage
Что в следующий раз
Теперь, когда мы знаем, как устроены самые популярные REST API, в следующий раз возьмём один из фреймворков для написания API и напишем свой. А вы пока подпишитесь, чтобы не пропустить продолжение и тоже написать что-то своё.
