API расшифровывается как Application Programming Interface — интерфейс программирования приложений. Звучит сухо, поэтому начнём с трёх бытовых аналогий.

Розетка

Электричество в доме генерится сложной электростанцией, проходит подстанции, понижающие трансформаторы и километры кабеля. Чтобы зарядить телефон, об этом ничего не нужно знать. Достаточно воткнуть зарядку в розетку. Розетка — интерфейс к электросети. Стандартная форма, стандартное напряжение, стандартные действия «воткнул — работает».

API делает то же самое для программ. Где-то на сервере крутится сложная система — база данных, бизнес-логика, очереди, ML-модели. Чтобы получить из неё данные, не нужно знать её устройство. Достаточно «воткнуть» запрос в нужный URL по нужному формату — и получить ответ.

Переводчик

Представьте, что вам нужно поговорить с человеком, который не знает вашего языка. Между вами стоит переводчик: вы говорите фразу — он переводит и передаёт собеседнику. Тот отвечает на своём языке — переводчик передаёт ответ вам.

Сайт и сервер тоже говорят на разных языках. Сайт — на JavaScript, сервер часто на Python или Java, база — на SQL. Прямого разговора между ними нет. API — тот самый переводчик: на одном конце клиент шлёт запрос на понятном формате (обычно — HTTP-запрос с JSON в теле), на другом сервер получает его, переводит во внутренние операции, выполняет и возвращает ответ в том же понятном формате.

Официант в ресторане

Третья аналогия особенно полезна, потому что описывает не только интерфейс, но и сам диалог.

Вы пришли в ресторан, садитесь за стол. На кухне готовят шеф-повар и команда; они умеют делать десятки блюд, у них куча ингредиентов, они знают, какие комбинации работают. Но вы с ними не общаетесь напрямую — вы общаетесь с официантом. Перед вами лежит меню — список того, что можно заказать. Вы говорите официанту: «Принесите пасту карбонара и стакан воды». Через десять минут официант приносит на подносе именно эти позиции. Если карбонара кончилась — он возвращается с сообщением «к сожалению, пасты нет, есть лазанья». Если кухня не справилась с заказом — «извините, сегодня шеф заболел».

В этой картине:

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

API не обязательно про сеть

Сейчас, когда в индустрии говорят «API», чаще всего имеют в виду веб-API — что-то, что лежит за HTTP-запросом. Но строго говоря, API — любой контракт между двумя программами. Когда вы пишете в JavaScript document.querySelector('.button'), вы пользуетесь API браузера — набором функций, через которые JavaScript управляет страницей. Когда из Node.js дёргаете fs.readFile(), вы пользуетесь API файловой системы. Тут нет сети, нет JSON, нет официантов — но есть интерфейс и он стандартизирован.

В этом курсе нас интересуют веб-API: те, что отвечают по HTTP. Среди них самая популярная разновидность — REST API. О ней — следующая глава.