У всей техники вокруг нас есть свой интерфейс — с его помощью мы можем ей управлять. Например, для автомобиля это руль и педали, у телевизора — пульт, а у микроволновки — кнопки на передней панели. Без этого пользоваться техникой у нас бы не получилось: мы не можем напрямую замыкать контакты, чтобы она делала то, что нам нужно.
В ИТ всё то же самое: у программ, сервисов, приложений и серверов тоже есть свой интерфейс. Мы сейчас не про внешнее оформление, а о том, как можно со всем этим хозяйством работать напрямую, чтобы получать нужный результат. Проще говоря, программный интерфейс — это про то, как, куда и какую команду отправить, чтобы программа сделала то, что мы хотим. Самое классное — в том, что нам не нужно знать, как программа это будет делать внутри себя, и всё, что от нас требуется, — это команды и обработка результатов. Всё вместе это называется API, и про него сегодняшний рассказ на примере REST API.
API — это аббревиатура от английского Application Programming Interface, интерфейс программирования приложения. Чтобы было понятнее, расшифруем так:
API — это то, что может делать программа по просьбе других приложений.
Само по себе приложение, сервис или программа не умеют работать с другими программами — они делают то, что нужно, и не обращают внимания на внешний мир. Но если разработчик добавит поддержку API в свою программу, то она научится обрабатывать не только свои данные, но и данные из других приложений.
Как работает REST API изнутри
API — это просто набор функций, которые добавили разработчики в программу, чтобы эта программа могла реагировать на внешние запросы по каким-то своим правилам. Сами правила тоже устанавливают разработчики: как они напишут API, так с этой программой и можно будет работать. Но чтобы не городить зоопарк из сотен разных подходов и сервисами было удобнее пользоваться, есть несколько принципов, по которым как раз и создаются API. Обычно их стараются придерживаться, но бывают и исключения.
REST API — cамый популярный сегодня вид API. Название образуется от английского REpresentational State Transfer, что можно перевести как «передача самоописываемого состояния». Принципы REST API состоят в том, чтобы использовать стандартные HTTP-запросы:
GETзапрашивает информацию;POSTотправляет информацию;PUTобновляет данные на сервере;DELETEудаляет указанные записи.
Это основные операции при работе с данными, они обозначаются аббревиатурой CRUD (create, read, update, delete — создание, чтение, обновление и удаление).
Информацией по REST API обмениваются чаще всего в формате JSON. Например, такой ответ можно получить, если запросить случайный факт из математики:
{
"text": "the smallest natural number representable in two different ways as a sum of two positive cubes, as Ramanujan stated on the spot",
"number": 1729,
"found": true,
"type": "math"
}Кроме REST API, есть и другие:
- GraphQL API;
- SOAP API;
- WebSocket API;
- gRPC API.
Каждый из них устроен и работает немного по-своему: например, вместо JSON используется бинарный формат или связь происходит не по HTTP, а по WebSocket. Мы сегодня говорим только про REST API, а остальные разберём в других статьях.
Читаем документацию по REST API
REST API — это не конкретные функции, которые нужно добавить в код, а принципы, по которым одно приложение может работать с другим. Это значит, что разработчики берут эти принципы и на их основе пишут свой API. Внутри будет всё по правилам REST, но сам формат запросов и ответов меняется в зависимости от того, что делает приложение и к чему хотят дать доступ разработчики.
Чтобы объяснить другим принцип работы своего API, разработчики пишут документацию. Она может выглядеть по-разному, вот несколько примеров.
Numbers API — программа, которая выдаёт разные факты о числах по запросам. Документация к ней выложена на двух ресурсах. На отдельном лендинге документация выглядит так — почти все возможности уместились на одном экране:
Ещё вариант — посмотреть документацию к Numbers API (и другим) на маркетплейсе RapidAPI. Здесь есть шаблоны запросов на разных языках, а информация структурирована по разделам. Но в этом случае запросы идут через маркетплейс, и для их выполнения нужно будет создать аккаунт RapidAPI. Неудобно, но иногда нужно:
Для следующего варианта документации рассмотрим SpaceX API. Он даёт доступ к информации о компании, которая производит ракеты. Через запросы можно узнать подробности о самой компании, полётах, истории и оборудовании.
Насколько эти данные связаны с настоящей SpaceX, неизвестно. В документации есть предупреждение, что с реальной компанией Илона Маска SpaceX API не связан никак. Но чтобы научиться читать документацию и для тренировки — сгодится.
Описание работы выложено на GitHub:
Jikan API — база данных аниме и манги, которая проверяет содержимое сайта myanimelist.net. Часто API-документация выглядит именно так:
Посмотреть список других публичных API и ссылки на них можно на странице github.com/public-api-lists/public-api-lists
Работаем с REST API
Посмотрим работу с REST API на примере SpaceX API. Если взглянуть на файл readme.md, можно найти описания всех существующих разделов:
Попробуем посмотреть раздел про экипаж (crew). Внутри есть четыре файла:
- all.md;
- one.md;
- query.md;
- schema.md.
Если мы откроем файл all.md, то увидим вверху заголовок Get all crew — «получить список всего экипажа».
Дальше описаны:
- метод запроса;
- URL для отправки;
- отметка о том, что авторизация не требуется;
- пример ответа.
Пример ответа тоже можно изучить. Это код в формате списка:
[
{
"name": "Robert Behnken",
"agency": "NASA",
"image": "https://imgur.com/0smMgMH.png",
"wikipedia": "https://en.wikipedia.org/wiki/Robert_L._Behnken",
"launches": [
"5eb87d46ffd86e000604b388"
],
"status": "active",
"id": "5ebf1a6e23a9a60006e03a7a"
},
...
]Можно понять, что GET-запрос на адрес https://api.spacexdata.com/v4/crew вернёт нам следующую информацию:
- имя;
- место работы;
- фото;
- ссылку на Википедию;
- идентификаторы полётов;
- статус — "
active", "inactive", "retired", "unknown"; - личный id;
- три точки в конце говорят, что это только один шаблон данных, на самом деле их будет какое-то неизвестное количество — в зависимости от команды.
Остальные файлы в папке crew выглядят примерно так же и описывают разные виды обращений к API.
One.md описывает правила запроса о конкретном члене экипажа по его личному id, который можно узнать из документации или сделав запрос по всей команде.
Schema.md показывает общее устройство ответа: тип данных каждого поля и значение по умолчанию. Например, так выглядит информация об имени человека:
"name": {
"type": "String",
"default": null
}Query.md описывает более сложные настраиваемые виды запросов и даёт ссылки на дополнительные ресурсы.
В итоге можно потратить на изучение документации 15–20 минут и примерно понять, как это можно применить.
Что делать с API-ответами
Всё это можно применить на фронтенде и показать пользователям. Для этого нужно посмотреть документацию и понять, что за информацию выдаёт API. После этого полезные параметры можно выделить и показать пользователю: на веб-странице, в мобильном приложении или телеграм-боте.
Иногда разработчики рассказывают, где уже применяется созданный ими API. Можно посмотреть, вдохновиться готовыми решениями и написать своё. Например, у Jikan API есть отдельная страница Showcase, где представлены использующие этот API сервисы:
Что дальше
В следующий раз расскажем о том, как разработчики тестируют REST API: какие инструменты используют, как разбирают ответы и что ещё можно узнать из ответов сервера. Подпишитесь, чтобы не пропустить продолжение.
