API

Что означает аббревиатура API простыми словами

В русском языке аббревиатуру переводят как «программный интерфейс приложения» или «интерфейс прикладного программирования». В текстах её нередко пишут кириллицей — «апи».

Интерфейс — точка контакта между двумя программами. Слово «программный» указывает на то, что взаимодействуют программы, а пользователь в обмене данными не участвует.

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

Программа, которой нужны данные другого сервиса, обращается к его API. Клиентское приложение отправляет запрос, API передаёт его на сервер и даёт ответ.

Обмен состоит из четырёх шагов:

1. Клиент формирует запрос: адрес, метод, параметры и данные для авторизации.
2. API проверяет, что запрос корректен и у клиента есть права.
3. Сервер обрабатывает запрос: читает данные из базы или выполняет действие.
4. API возвращает ответ с кодом статуса и данными, чаще всего в формате JSON.

Для чего нужен API

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

Из чего состоит API

Любой API состоит из элементов, которые описаны в его документации:

• Эндпоинт (endpoint) — адрес, на который клиент отправляет запрос. 
• Метод — тип действия. GET запрашивает данные, POST создаёт запись, PUT и PATCH изменяют существующую, DELETE удаляет.
• Параметры — уточнения к запросу: город, дата, номер заказа.
• Заголовки — служебная информация: формат данных, ключ или токен доступа.
• Тело запроса — данные, которые клиент передаёт серверу при создании или изменении записи.
• Ответ — данные и код статуса, по которому клиент понимает результат.

Виды API

По доступности

• Открытые (публичные) API. К ним подключается любой разработчик, обычно после регистрации и получения ключа.
• Партнёрские API. Доступ получают только компании, которые заключили соглашение с владельцем сервиса.
• Внутренние (приватные) API. Они связывают части одной системы внутри компании и не публикуются внееё.

По архитектуре и протоколу

API бывает не только веб-ориентированным. Операционные системы и библиотеки тоже предоставляют программам интерфейсы: например, Windows API позволяет приложению открыть окно или прочитать файл.

Чем API отличается от REST API

API — общее понятие: любой интерфейс, через который программы взаимодействуют. REST API — конкретная реализация, которая следует принципам REST:

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

SOAP, GraphQL и gRPC тоже относятся к API, но принципам REST не следуют.

API-ключ, токен и авторизация

API должен знать, кто к нему обращается. Для этого используют два основных механизма:

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

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

Интеграция по API

Интеграция по API — автоматический обмен данными между двумя системами без ручного переноса. Интернет-магазин передаёт заказы в складскую систему, форма на сайте создаёт заявку в CRM, служба доставки отдаёт статус посылки.

Данные из другой системы получают двумя способами:

• Запрос по расписанию (polling). Система регулярно обращается к API и спрашивает, появились ли изменения. Способ простой, но создаёт лишние запросы, а данные приходят с задержкой.
• Webhook. Система-источник сама отправляет уведомление на заданный адрес, когда происходит событие: создан заказ, оплачен счёт, завершён звонок. Данные приходят сразу, лишних запросов нет.

Где встречается API

• Оплата на сайте. Магазин передаёт платёжному сервису сумму и получает подтверждение.
• Вход через аккаунт другого сервиса. Сайт получает подтверждение личности по протоколам OAuth 2.0 и OpenID Connect и не хранит пароль пользователя.
• Карты на сайтах. Страница запрашивает у картографического сервиса координаты и маршрут.
• Чат-боты в мессенджерах. Бот принимает сообщения и отправляет ответы через API мессенджера.
• Маркетплейсы. Продавец выгружает остатки и получает заказы без входа в личный кабинет.

Типичные ошибки при работе с API

Код статуса в ответе показывает, что пошло не так:

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