Что такое API и зачем он нужен

Урок объясняет, что такое API, почему две программы договариваются заранее и как этот договор работает в вебе.

API (Application Programming Interface) — это набор правил, по которым одна программа обращается к другой: какие запросы можно отправлять, в каком формате и что придёт в ответ.

Когда вы заходите в кафе, вы не идёте на кухню готовить сами — вы делаете заказ через официанта по понятному меню. Меню перечисляет, что можно заказать; официант принимает заказ и приносит результат; внутренняя кухня остаётся скрытой. API — это меню и официант между двумя программами. Одна программа (клиент) хочет получить или изменить данные, другая (сервер) умеет это делать, и между ними есть строго описанный способ общения.

Зачем вообще нужен API

Представьте мобильное приложение погоды. Оно не измеряет температуру само — у телефона нет метеостанции. Вместо этого приложение отправляет запрос на сервер метеослужбы: «дай прогноз для Москвы на сегодня». Сервер возвращает данные, приложение их красиво рисует. Приложение и сервер написаны разными командами, на разных языках, работают на разных устройствах — и всё равно понимают друг друга, потому что у них есть общий контракт: API.

Главная ценность API — разделение труда и сокрытие сложности. Клиенту не нужно знать, как сервер хранит данные, какая у него база, на каком языке он написан. Достаточно знать контракт: «отправь такой запрос — получишь такой ответ». Это позволяет:

Переиспользовать функциональность. Один сервер платежей обслуживает тысячи магазинов.
Менять реализацию незаметно. Кухню можно переоборудовать, пока меню не меняется — гость ничего не заметит.
Соединять разные системы. Сайт на одном языке общается с сервисом на другом.

API как контракт между системами

Слово «контракт» здесь не метафора, а суть. Контракт описывает обязательства обеих сторон. Клиент обязуется отправлять запрос в оговорённом виде; сервер обязуется отвечать в оговорённом виде. Если одна сторона нарушает контракт — общение ломается.

Контракт обычно фиксирует четыре вещи:

Часть контракта	Что описывает
Адрес (endpoint)	куда отправлять запрос: `/users/42`
Операция	что мы хотим сделать: получить, создать, удалить
Формат запроса	какие данные и в каком виде передаём
Формат ответа	что и в каком виде вернётся, какие коды ошибок

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

Клиент и сервер

В вебе общение почти всегда устроено по модели клиент-сервер. Клиент — тот, кто инициирует запрос (браузер, мобильное приложение, другой сервис). Сервер — тот, кто слушает запросы и отвечает. Клиент всегда начинает разговор; сервер сам по себе ничего не присылает.

   КЛИЕНТ                          СЕРВЕР
  (браузер,        запрос          (хранит
   приложение)  ------------>      данные,
               <------------       логику)
                  ответ

Один сервер обслуживает множество клиентов одновременно. Поэтому каждый запрос должен быть самодостаточным — об этом подробно в уроке про stateless.

HTTP как транспорт

Чтобы запрос доехал от клиента до сервера, нужен транспортный протокол — общий язык передачи. В вебе это HTTP (HyperText Transfer Protocol). Это тот же протокол, по которому браузер загружает страницы, только вместо HTML-страниц по нему ходят данные.

HTTP-запрос — это обычный текст с понятной структурой: строка с операцией и адресом, заголовки (метаданные) и необязательное тело. Вот как выглядит «сырой» запрос на получение пользователя:

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

А вот ответ сервера — строка статуса, заголовки и тело с данными:

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Анна"}

Ключевые элементы HTTP, которые нам понадобятся на протяжении всего курса:

Метод (глагол) — что делаем: GET, POST, PUT, DELETE.
URL — адрес ресурса: /users/42.
Заголовки — метаданные: формат, авторизация, кэширование.
Тело — сами данные (есть не у всех запросов).
Код статуса — итог: 200 успех, 404 не найдено, 500 ошибка сервера.

Формат обмена данными

Контракт должен оговаривать не только канал, но и язык данных. Самый распространённый формат для веб-API — JSON (JavaScript Object Notation). Он читаем человеком и легко разбирается любым языком программирования:

{
  "id": 42,
  "name": "Анна",
  "active": true,
  "roles": ["editor", "reviewer"]
}

Раньше широко использовали XML — он многословнее и тяжелее. JSON выиграл за счёт лаконичности. Важно: формат — это часть контракта. Клиент сообщает заголовком Accept: application/json, что хочет JSON, а сервер заголовком Content-Type: application/json подтверждает, что прислал именно его.

Как работает под капотом

Проследим путь одного запроса от нажатия кнопки в приложении до данных на экране:

Приложение формирует HTTP-запрос: метод GET, адрес /users/42, заголовок Accept: application/json.
Имя api.example.com через DNS превращается в IP-адрес сервера.
Устанавливается TCP-соединение (и поверх него TLS, если адрес начинается с https — шифрование).
Запрос уходит на сервер. Тот разбирает его, понимает «нужен пользователь 42», лезет в базу данных.
Сервер собирает ответ: код статуса 200 OK, заголовок Content-Type: application/json и тело с JSON.
Ответ возвращается клиенту, приложение разбирает JSON и рисует имя на экране.

Важно понять: API не зависит от языка и платформы. Сервер может быть на Python, клиент — на Kotlin, и они прекрасно общаются, потому что между ними не код, а текстовый протокол и текстовый формат данных. В этом сила веб-API.

Частые ошибки

Путать API и сервер. Сервер — это программа, которая работает. API — это описание правил общения с ней. Один сервер может предоставлять несколько API.
Думать, что API — это обязательно про интернет. API есть и внутри программы (библиотеки). Веб-API — частный, но самый обсуждаемый случай.
Считать, что клиент видит внутренности сервера. Наоборот: API специально скрывает реализацию. Клиент знает только контракт.
Игнорировать формат. Если сервер прислал JSON, а клиент ждёт XML, общение сломается, хотя HTTP-уровень был успешен.

Итог

API — это контракт: правила, по которым одна программа обращается к другой.
Веб-API строятся на модели клиент-сервер: клиент инициирует запрос, сервер отвечает.
HTTP — транспорт: метод, URL, заголовки, тело, код статуса.
JSON — самый распространённый формат обмена данными; формат тоже часть контракта.
API скрывает сложность и не зависит от языка и платформы сторон.