API (Application Programming Interface, интерфейс программирования приложений) — это контракт, который описывает, как одна программа может обращаться к функциям или данным другой, не зная ее внутреннего устройства. Простыми словами, это набор правил: какие запросы можно отправить, в каком формате и что придет в ответ. В статье разберем устройство API на примере клиент-серверной модели, различим API, REST, HTTP и эндпоинт, и отправим реальный запрос к публичному тестовому серверу.
Содержание
API, REST, HTTP, эндпоинт: в чем разница
Эти четыре термина часто путают, хотя они описывают разные уровни одной системы.
- API — самое широкое понятие, контракт взаимодействия программ. API может быть локальным (функции библиотеки внутри одной программы) или сетевым (запросы через интернет).
- REST — архитектурный стиль построения именно сетевых API: набор принципов, как раскладывать данные по адресам и какими методами их менять. REST — это один из способов сделать API, не единственный.
- HTTP — сетевой протокол передачи данных, на котором чаще всего работает REST API. HTTP определяет, как выглядит запрос и ответ на уровне байтов и заголовков, а не что именно означают данные внутри.
- Эндпоинт (endpoint) — конкретный URL-адрес внутри API, за которым закреплена одна операция или один ресурс, например
/posts/1.
Проще говоря: HTTP — это транспорт, REST — правила, по которым транспорт используется, API — весь контракт целиком, а эндпоинт — одна точка входа в этот контракт.
Как устроено взаимодействие: клиент и сервер
В основе большинства API лежит модель клиент-сервер.
Сервер хранит данные и логику, ждет запросов и отвечает на них. Он работает постоянно и не инициирует общение сам.
Клиент — программа, которая отправляет запросы: мобильное приложение, сайт в браузере, скрипт на Python. Клиент формирует запрос, указывает нужный эндпоинт и метод, ждет ответ и обрабатывает его.
Между ними работает протокол (чаще всего HTTPS — HTTP поверх шифрования TLS). Один и тот же сервер может обслуживать множество разных клиентов одновременно, если каждый запрос самодостаточен и не требует помнить предыдущие обращения клиента — на этом принципе строится REST.
Методы запроса и коды ответа
У HTTP есть методы — они говорят серверу, какое действие нужно выполнить над ресурсом.
| Метод | Что делает | Пример |
|---|---|---|
| GET | получить данные, не изменяя их | получить список постов |
| POST | создать новый ресурс | отправить новый пост |
| PUT/PATCH | обновить существующий ресурс (полностью/частично) | изменить текст поста |
| DELETE | удалить ресурс | удалить пост |
Сервер отвечает не только данными, но и кодом статуса — числом, которое сразу показывает, что произошло.
| Код | Значение |
|---|---|
| 200 | OK, запрос выполнен успешно |
| 201 | Created, ресурс создан |
| 400 | Bad Request, ошибка в самом запросе |
| 401 | Unauthorized, нужна авторизация |
| 404 | Not Found, ресурс с таким адресом не существует |
| 500 | Internal Server Error, ошибка на стороне сервера |
Код ответа стоит проверять всегда, даже если пришел JSON: сервер может вернуть тело ошибки с кодом 400 или 500, и его легко принять за обычные данные, если не посмотреть на статус.
Пример: запрос к публичному тестовому API
Для тренировки удобно использовать открытый сервис httpbin.org — он создан для отладки HTTP-запросов, не требует ключа доступа и просто отражает то, что вы отправили. Это удобно, чтобы увидеть устройство запроса и ответа, ничего не настраивая.
Сначала GET-запрос на Python — запрашиваем служебный ответ сервиса с параметром:
import requests
response = requests.get("https://httpbin.org/get", params={"id": 1})
print(response.status_code)
print(response.json())Ожидаемый результат: строка 200 (код ответа) и следом словарь Python. В нем сервис вернет детали вашего запроса: под ключом args будут переданные параметры ({"id": "1"}), под headers — заголовки, под url — итоговый адрес. Метод .json() сам разбирает тело ответа из формата JSON в обычный словарь.
Тот же запрос через curl в терминале (только ASCII-дефисы в опциях):
curl -i "https://httpbin.org/get?id=1"Флаг -i выводит заголовки ответа вместе с телом, поэтому первой строкой видно HTTP/2 200 и заголовок content-type: application/json, а ниже — JSON с деталями запроса.
Теперь POST-запрос — отправляем новые данные:
curl -s -X POST https://httpbin.org/post \
-H "Content-Type: application/json" \
-d '{"title": "test", "body": "privet", "userId": 1}'Сервис вернет код 200 и JSON, где под ключом json будут ровно те поля, что вы отправили. Это не значит, что данные где-то сохранились: httpbin.org только отражает запрос обратно и ничего не пишет в базу — при повторном запросе никакого нового ресурса там не появится.
Разбор ошибки: если отправить тот же POST без заголовка Content-Type: application/json, сервер не поймет, что тело — это JSON. В ответе поле json будет null, а данные попадут в form как обычный текст. Исправление — всегда явно указывать заголовок Content-Type при отправке JSON-тела.
Виды API
Чаще всего в вебе встречаются такие подходы к построению API.
| Вид | Формат данных | Особенность |
|---|---|---|
| REST | обычно JSON | простые правила, самый частый выбор для веб-сервисов |
| SOAP | строго XML | жесткая стандартизация, распространен в банковских и корпоративных системах |
| GraphQL | JSON | клиент сам описывает, какие поля нужны, за один запрос |
| RPC (в т.ч. gRPC) | бинарный формат или JSON | вызов удаленной функции выглядит как обычный вызов функции в коде |
Различие важно на практике: в REST клиент обычно получает от эндпоинта фиксированный набор полей, даже если нужна только часть из них. В GraphQL клиент сам перечисляет нужные поля в запросе — это удобно, когда мобильному приложению и веб-версии нужны разные данные с одного и того же сервера.
Как вызвать API в проекте
API вызывают двумя способами.
Напрямую — когда код сам формирует запрос к эндпоинту, например через библиотеку requests в Python или fetch в JavaScript. Так делают интеграции между сервисами и автотесты.
Косвенно — когда пользователь нажимает кнопку в интерфейсе, а приложение уже само отправляет запрос к API за кулисами. Например, нажатие «Сохранить» в веб-форме запускает PUT-запрос, которого пользователь не видит.
Выводы
- API — контракт взаимодействия программ; REST — один из архитектурных стилей построения сетевого API, а не синоним API.
- HTTP — транспортный протокол, эндпоинт — конкретный адрес операции внутри API.
- Клиент отправляет запрос с методом (GET/POST/PUT/PATCH/DELETE), сервер отвечает данными и кодом статуса (200, 201, 400, 404, 500).
- Перед разбором ответа стоит проверять код статуса, а не только наличие тела ответа.
- REST, SOAP, GraphQL и RPC решают одну задачу по-разному: выбор зависит от требований к гибкости выборки данных, строгости стандарта и формата.
Где применяется / связь с практикой
Освойте тему на практике
Работа с API — обязательный навык на курсе Проектирование API: там разбирают проектирование REST и GraphQL интерфейсов, версионирование и обработку ошибок на реальных кейсах, а не на тестовом сервисе. Если пока не готовы к полному курсу, можно начать с открытых уроков Otus — формат бесплатный, подходит для первого знакомства с темой.
FAQ
Нужен ли ключ доступа для любого API?
Нет, часть публичных API (в том числе httpbin.org из примера выше) открыта без авторизации. Но у большинства коммерческих сервисов есть ключ (API key) или токен, который передается в заголовке запроса и определяет, какому клиенту разрешен доступ и в каком объеме.
Чем API отличается от SDK?
API — это контракт (описание запросов и ответов), а SDK (Software Development Kit) — готовый набор кода и инструментов на конкретном языке программирования, который уже реализует обращение к этому API за разработчика. SDK удобнее, но не обязателен: к любому REST API можно обратиться напрямую HTTP-запросом без SDK.
Что произойдет, если отправить запрос на несуществующий эндпоинт?
Сервер вернет код 404 (Not Found) и обычно короткое сообщение об ошибке в теле ответа. Это не ошибка сети — соединение с сервером установилось успешно, но по указанному адресу для конкретного API ничего не зарегистрировано.
