Как программы договариваются между собой
API — это набор правил, по которым одна программа обращается к другой. Расшифровывается как application programming interface, по-русски — программный интерфейс приложения. В разговоре говорят и пишут «апи». Это не сама программа, не сервер и не протокол, а договор: какие запросы можно сделать, какие данные передать и что вернётся в ответ.
У каждой программы, с которой можно взаимодействовать программно, есть API. У библиотеки это набор функций, у операционной системы — системные вызовы, у браузера — возможности, которые он даёт скриптам страницы. Когда говорят об API сервиса, обычно имеют в виду сетевой API — частный случай, где программа обращается к серверу по сети. Но сеть не обязательна: API нейросети — тот же договор, по которому программа отправляет запрос модели и получает ответ, даже если модель работает на том же компьютере.
Представьте интернет-магазин и службу доставки. Магазин не привозит заказы сам, а договаривается со службой: передаёт адрес, вес посылки и срок, а взамен получает номер отслеживания и стоимость. API здесь — правила этой договорённости: какие данные передать, в каком формате и что ожидать в ответ. Если служба изменит правила, магазин не сможет отправить заказ, пока не перепишет свой код.
Тот же принцип работает и в других случаях. Приложение прогноза погоды обращается к API метеослужбы, касса — к API налоговой, а мобильное приложение — к API сервера, который хранит данные пользователей. Когда программа или сервис просят «вставить API-ключ», им нужна строка, с которой они будут обращаться к API от имени вашей учётной записи, — так же программа магазина предъявляет службе доставки ключ магазина, когда отправляет заказ. Выдаёт ключ тот сервис, к чьему API пойдут запросы, и это не обязательно тот, кто ключ просит.
Из чего состоит вызов
Речь пойдёт об API сервиса, доступном по сети, — чаще всего он работает по протоколу HTTP, как и веб-страницы. Вызов API по HTTP состоит из четырёх частей:
- Метод — что сделать: получить данные, создать запись, изменить или удалить. Например, получить прогноз погоды — это один метод, а отправить заказ на доставку — другой.
- Адрес — куда отправить запрос. В разговоре адрес называют эндпоинтом или «ручкой». Например, адрес для получения прогноза может выглядеть как
weather.example.com/forecast, а для отправки заказа —delivery.example.com/orders. - Заголовки — дополнительная информация о запросе: кто обращается, в каком формате ожидает ответ, какой ключ предъявляет.
- Тело — сами данные, если они нужны. Например, при отправке заказа в теле передают адрес, вес и содержимое посылки.
В ответ сервис возвращает:
- Код состояния — чем закончился запрос, в общих чертах. Тому, кто подключается к API, достаточно различать три группы кодов: получилось, ошибся вызывающий (запрос составлен неверно или не может быть выполнен) и ошибся сервер. Групп больше, но для подключения хватает этих трёх. И успешный код ещё не значит, что операция выполнена: встречаются API, которые на неудавшуюся операцию отвечают успешным кодом. Конкретная причина ошибки лежит в теле ответа, и её формат у каждого сервиса свой. Как выбирают коды ответа и форму ошибки те, кто API проектирует, разобрано в материале о проектировании API.
- Заголовки — дополнительная информация об ответе: в каком формате данные, сколько их, когда они обновлялись.
- Тело — сами данные, если они есть. Например, прогноз погоды или номер отслеживания заказа.
Ключ: кто обращается и почему его нельзя показывать
Чтобы сервис понимал, кто к нему обращается, в запросе передают ключ API. Это строка, которую обычно создают в настройках учётной записи сервиса. Ключ опознаёт вызывающее приложение или учётную запись, а не человека за экраном. Это не пароль пользователя, и ключ нужен не каждому API.
Ключ передают обычно в заголовке запроса. Сервис проверяет ключ и решает, можно ли выполнить запрос. Если ключ недействителен или у него нет прав на операцию, сервис отвечает ошибкой. Например, код 401 обычно означает, что в запросе нет действительных учётных данных — ключа нет или он не годен. Код 403 обычно значит, что сервер понял запрос, но отказывается его выполнять, и причина не обязательно в ключе. Чем эти отказы различаются по существу, разобрано в материале об аутентификации и авторизации, а как отвечает конкретный сервис, сказано в его документации.
Ключ — предъявительский: кто предъявил, тому сервис и поверил. Если ключ попадёт в чужие руки, злоумышленник сможет действовать от имени владельца ключа. Поэтому секретный ключ нельзя класть в код страницы или приложения: всё, что отдано на устройство пользователя, пользователь может прочитать.
Например, если встроить секретный ключ в код страницы интернет-магазина, любой посетитель сможет его извлечь и отправить запросы от имени магазина. Выход — вызывать API через свой сервер, а не напрямую из браузера. На сервере ключ хранится в безопасности, и запросы к API сервиса отправляет сервер, а не браузер пользователя.
Бывают и публичные ключи, которые поставщик сам объявил безопасными для встраивания в код. Такой ключ обычно ограничивает набор доступных операций или объём данных, чтобы злоупотребление не наносило ущерба. Но даже публичный ключ не стоит считать безопасным без проверки: иногда владелец должен включить ограничения вручную, иначе ключ даёт больше прав, чем кажется.
Если ключ утёк, его отзывают и выпускают новый. «Сменить пароль» у ключа нельзя: ключ — это вся строка целиком, её не редактируют, а заменяют другой.
Ключ и токен доступа — разные вещи, хотя сервисы нередко называют токеном и сам ключ. Ключ обычно выдаётся в кабинете сервиса, живёт долго и опознаёт приложение или учётную запись. Токен доступа обычно выдаётся после входа пользователя, живёт ограниченное время и действует в пределах выданных прав. Но по названию это не отличить: долгоживущую строку из кабинета тоже могут назвать токеном. Различают их по тому, как строка выдана и сколько живёт. Токены языковой модели — другое понятие: слово одно, а вещи разные.
Интеграция: что обещают и почему ломается
Когда говорят об «интеграции по API», имеют в виду одно из двух. Либо готовый соединитель между двумя конкретными системами — например, плагин для кассы, который сам передаёт данные в учётную программу. Либо «API у нас есть, интеграцию пишите сами»: сервис предоставляет описание, а разработку и сопровождение ложатся на покупателя.
API бывает трёх типов:
- Публичный — доступен всем, кто зарегистрировался. Например, API прогноза погоды или карт.
- Партнёрский — доступен по договору. Например, API платёжной системы для магазинов.
- Внутренний — предназначен только для собственных программ компании: описания для посторонних у него нет. Например, API, которым пользуется собственный интерфейс сайта: запросы к нему уходят из браузера посетителя, так что увидеть их можно, но договором для посторонних он от этого не становится.
Слова «у нас есть API» без уточнения, какой именно, ничего не обещают. Даже публичный API может изменить правила или условия использования.
Интеграция ломается не только из-за изменения договора. Вот что может пойти не так:
- Договор изменили. Сервис удалил или переименовал поле, сменил его тип, добавил обязательный параметр или ужесточил проверку входных данных. Всё это ломает вызывающую программу, тогда как добавление необязательного поля в ответ обычно совместимо; как отличить одно от другого, зачем договору версии и когда запрос можно безопасно повторить — в материале о проектировании REST API.
- Ключ отозван или истёк. Сервис перестал принимать ключ, и запросы больше не проходят.
- Превышено ограничение. Сервис отвечает ошибкой, если запросов слишком много за короткий интервал или исчерпан объём доступных данных за расчётный период. Обычно на превышение частоты сервис отвечает кодом 429 и может подсказать, когда повторить запрос, но это не обязательно. Вызывающая программа должна уметь подождать и повторить запрос, а не слать их чаще.
- Сервер перегружен или находится на обслуживании, либо сеть оборвалась посреди запроса. Последний случай хуже остальных: ответ не пришёл, вызывающая программа не знает, выполнен ли запрос, и повтор запроса на создание может создать вторую запись.
Интеграция — это не только техническая задача, но и договорённость о том, кто и как будет её поддерживать. Если API меняется часто или без предупреждения, интеграция требует постоянных доработок.
Три соседних слова
REST — стиль построения API, а не синоним слова API. На практике REST API строят поверх HTTP: у ресурсов есть адреса, действия выражаются методами HTTP, а сервер хранит состояние самих ресурсов, но не состояние диалога между запросами — каждый запрос несёт всё нужное для обработки. Когда этот стиль подходит, а когда лучше выбрать другой, разобрано в материале о выборе стиля для своего API.
SDK — набор средств разработки, обычно подразумевается готовая библиотека для конкретного языка, которая сама собирает запросы к API. Это удобство поверх API, а не сам API. SDK может включать примеры кода, документацию и инструменты для тестирования.
Вебхук — вызов в обратную сторону: не клиент спрашивает сервер, а сервер сам обращается к клиенту, когда произошло событие. Например, служба доставки может отправить вебхук магазину, когда заказ доставлен. Для вебхука клиент должен предоставить адрес, доступный из сети, и проверять подлинность вызова — как это делается, разобрано в материале о подписи вебхука.
Тупик: когда API нет или описание неполное
Когда нужного API нет или его описание неполное, первое, что пробуют, — разобрать страницы сайта. Например, если интернет-магазин не предоставляет API для получения списка товаров, программа может загрузить страницу каталога и извлечь из неё названия, цены и описания. Это кажется простым решением: данные уже лежат на странице, и остаётся только их собрать.
Но интерфейс для людей — не договор. Вёрстка страницы меняется без предупреждения: разработчики сайта могут поменять расположение элементов, добавить новые блоки или изменить стили. Программа, которая разбирает страницу, может не упасть, а продолжить работать и приносить пустые или сдвинутые поля. Например, если раньше цена товара лежала в теге <span class="price">, а теперь её перенесли в <div class="product-price">, программа перестанет её находить. Хуже того, она может найти не ту цену — например, цену другого товара или скидку — и продолжить работать как ни в чём не бывало. Этот тихий случай и опасен: данные кажутся правильными, но на самом деле они неверны.
Следующий шаг — ручная выгрузка файла. Например, если API для выгрузки заказов нет, магазин может попросить службу доставки присылать файл с заказами в конце дня. Это тоже интерфейс для людей: состав и порядок столбцов меняют без объявления, а сам шаг зависит от того, что человек не забудет его выполнить. Если выгрузку забудут сделать, данные не обновятся, и программа продолжит работать со старыми данными. Если в файле поменяют порядок столбцов, программа может начать читать адрес как вес посылки, а стоимость — как номер заказа.
Внутренний API сайта, найденный в сетевых запросах страницы, обещаний тоже не даёт. Его меняют так же молча, как вёрстку, и интеграция ломается без предупреждения. Например, если раньше список товаров возвращался по адресу /api/products, а теперь его перенесли на /api/v2/products, программа перестанет получать данные. Если сервис добавит обязательный параметр или изменит формат ответа, программа может упасть или начать работать неверно.
Все эти решения — разбор страниц, ручная выгрузка, использование внутреннего API — не помогают, потому что они опираются на то, что не является договором. Интерфейс для людей не обещает стабильности, и полагаться на него — значит строить на зыбком фундаменте.
Позиция редакции
API — это то, что обещано в описании, а не то, что сейчас случайно работает. Опираться на недокументированное поведение — значит строить на том, что уберут без предупреждения. Договор односторонний: описание — признак намерения поддерживать, а не гарантия. Владелец может объявить версию устаревшей, изменить лимиты и условия использования.
Неверна эта позиция в двух случаях. Первый — когда обе программы принадлежат одной команде и меняются одновременно. Тогда описание может отставать от реального поведения, и источник правды — само поведение. Второй — когда описание отстаёт от реального поведения, но поведение стабильно и предсказуемо. Тогда договором становится поведение, а не описание.
В остальных случаях API — это то, что написано в документации, а не то, что работает сегодня. Если описания нет или оно неполное, интеграция строится на зыбком фундаменте. Разбор страниц или использование внутреннего API — временное решение, которое ломается при первом же изменении интерфейса. Лучше договориться об API или найти сервис, который его предоставляет.