Что такое API

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

Пример Twitter API

Пример. У твиттера есть сайт, на котором мы можем просматривать твиты. Кликая по ссылкам мы попадаем на разные адреса, по которым доступна разная информация: лента твитов, страница твита, личный кабинет, сброс пароля, рекламный кабинет и так далее.

https://twitter.com/mokevnin – страница конкретного пользователя
https://twitter.com/mokevnin/status/1446464250499710976 – страница конкретного твита

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

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

Именно здесь на помощь приходит API. Твиттер предоставляет специальные http-адреса, по которым доступны чистые данные, а не конкретные интернет-страницы с готовым внешним видом. Данные по таким адресам отдаются в структурированном формате, чаще всего JSON. Один сервис "упаковывает" данные в JSON формат, другой, который ходит за данными, "распаковывает" их из JSON и использует внутри себя для отображения. Пример запроса пользователя:

# Адрес, по которому возвращается список указанных пользователей
# В данном случае запрашивается один пользователь
https://api.twitter.com/2/users/by?usernames=hexletHQ

# В ответ приходит JSON такой структуры:
{
  "data": [
    {
      "created_at": "2013-12-14T04:35:55.000Z",
      "id": "2244994945",
      "name": "HexletHQ",
      "description": "Хекслет - курсы программирования",
      "pinned_tweet_id": "1464165859761573893",
      "username": "hexlethq"
    },
  ],
}

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

Кстати, сам твиттер использует свое API, в том числе для виджетов, которые можно встраивать на любой сайт для отображения конкретного твита или ленты твитов, хороший пример – главная Хекслета. И, если говорить откровенно, то сам сайт твиттера работает по API. В браузер грузится JS-код, который реализует логику вывода и ходит за данными на сервер (по API).

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

HTTP API

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

Но не все HTTP API одинаковые. HTTP оставляет многое на откуп разработчикам, поэтому разные HTTP API могут отличаться друг от друга кардинально, например, форматом данных. Самый популярный формат JSON, но кроме него используется и XML. XML и HTML очень похожи по внешнему виду, но XML описывает данные, а не то как они расположены и выглядят:

<!-- Просто пример API из интернета -->
<Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
</Contents>

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

Кроме форматов, HTTP API отличаются тем как у них структурированы адреса. Например у code-basics на каждый вид данных есть свой адрес:

https://code-basics.com/api/languages.json – список языков, по которым есть курсы
https://code-basics.com/api/languages/12.json – информация о курсе
https://code-basics.com/api/languages/12/lessons.json – список уроков курса по языку

Подобное API часто называют REST API. Подробнее о нем в другой статье. Иногда API выглядит так, что адрес всегда один, но на него отправляются разные параметры запроса. У данного способа есть множество разновидностей, например, json-rpc, graphql и другое:

# Все запросы идут только на этот адрес
https://some-site.com/api/rpc
https://some-site.com/api/rpc?param=value

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

Не HTTP API

API бывает не только HTTP. Обычно, такие API встречаются внутри сервиса, для взаимодействия его компонентов, каждый из которых ведет себя как маленький сервис. Такие API могут использовать как другой протокол, например TCP, так и строиться вообще поверх других подходов, например с помощью систем очередей или потоков. Ключевые слова: grpc, rabbitmq, kafka.

« Что такое интерпретатор

Что такое транспиляция »

Исходный код (github)

Кирилл Мокевнин