Что такое API простыми словами
API (Application Programming Interface, программный интерфейс приложения) - это набор правил, по которым одна программа просит другую что-то сделать или отдать данные. Программа-клиент отправляет запрос в оговорённом формате, программа-сервер отвечает тоже в оговорённом формате. Как устроен сервер внутри, клиенту знать не нужно.
Удобная аналогия - меню в кафе. Вы не идёте на кухню и не командуете поваром. Вы выбираете позицию из меню, официант передаёт заказ, через какое-то время приносит блюдо. Меню и есть API: список того, что можно заказать, и правила, как это сделать. Если попросить блюдо, которого в меню нет, вы получите отказ, а не импровизацию повара.
С API вы сталкиваетесь каждый день, даже если не пишете код:
- приложение погоды берёт прогноз у метеосервиса через его API;
- кнопка "Войти через Яндекс ID" или "Войти через VK" работает через API этих сервисов;
- интернет-магазин передаёт сумму платёжному шлюзу и получает статус оплаты;
- бот в Telegram получает и отправляет сообщения через Telegram Bot API.
Для разработчика API - это способ не изобретать всё самому. Не нужно строить свою карту, если можно запросить координаты у картографического сервиса. Не нужно хранить курсы валют, если их отдаёт банк.
Какие бывают API
Слово API используют в нескольких смыслах, и новичков это путает. Когда на собеседовании спрашивают "работали с API?", почти всегда имеют в виду веб-API, то есть обмен данными по сети через HTTP. Но есть и другие варианты.
| Вид | Где встречается | Пример |
|---|---|---|
| REST API | Большинство публичных веб-сервисов | GET /users/42 возвращает пользователя в JSON |
| GraphQL | Сложные интерфейсы, где клиент сам выбирает поля | Один адрес /graphql, запрос описывает нужные поля |
| gRPC | Общение микросервисов внутри компании | Бинарный формат Protocol Buffers, высокая скорость |
| SOAP | Банки, госсистемы, старые корпоративные системы | XML-конверты и строгая схема WSDL |
| API библиотеки | Любой язык программирования | Функции модуля json в Python |
| API браузера | Фронтенд | fetch, localStorage, Geolocation API |
Дальше речь пойдёт о REST API: с него начинают почти все, и именно его чаще всего просят в вакансиях junior-разработчиков.
REST API: принципы без зубрёжки
REST - это не протокол и не библиотека, а архитектурный стиль. Его описал Рой Филдинг в диссертации 2000 года. На практике REST API - это API поверх HTTP, которое придерживается нескольких договорённостей:
- Всё - ресурсы. Пользователь, заказ, товар. У каждого ресурса есть адрес:
/users- список пользователей,/users/42- конкретный пользователь. - Действие задаёт HTTP-метод, а не адрес. Правильно
DELETE /users/42, неправильноGET /deleteUser?id=42. - Сервер не помнит клиента между запросами (stateless). Каждый запрос несёт всё нужное, включая токен авторизации.
- Клиент и сервер разделены. Одно и то же API обслуживает сайт, мобильное приложение и чужие интеграции.
- Ответы можно кешировать, если сервер это разрешил заголовками.
Строго "по Филдингу" REST реализован редко. Когда разработчики говорят "у нас REST", чаще имеют в виду: ресурсы в URL, методы HTTP, данные в JSON, понятные коды ответа. Для старта этого достаточно.
HTTP-методы и эндпоинты
Эндпоинт (endpoint) - это конкретный адрес API плюс метод. GET /orders и POST /orders - два разных эндпоинта, хотя путь одинаковый. Основные методы:
- GET - получить данные. Ничего не меняет на сервере, повторный вызов безопасен.
- POST - создать новый ресурс. Два одинаковых POST обычно создадут два заказа.
- PUT - заменить ресурс целиком.
- PATCH - изменить часть полей, например только email.
- DELETE - удалить ресурс.
Свойство "повтор не меняет результат" называют идемпотентностью. GET, PUT и DELETE идемпотентны, POST нет. Это важно, когда запрос оборвался по таймауту и клиент решает, можно ли его безопасно повторить.
Ещё одна деталь - параметры. Фильтры и сортировку обычно передают в строке запроса: GET /products?category=books&sort=price&page=2. Данные для создания или изменения передают в теле запроса, чаще всего в формате JSON.
Из чего состоят запрос и ответ
Любой обмен с REST API - это пара "запрос - ответ". В запросе четыре части:
- метод - GET, POST и так далее;
- URL - адрес ресурса с параметрами;
- заголовки - служебная информация:
Content-Type: application/json,Authorization: Bearer ...; - тело - данные, которые вы отправляете (у GET тела обычно нет).
Ответ сервера состоит из кода статуса, заголовков и тела. Код показывает итог одним числом: 200 - всё хорошо, 201 - ресурс создан, 404 - не найдено, 500 - сломалось на сервере. Подробный разбор всех частых кодов есть в статье про коды ответов HTTP.
Тело ответа современные API почти всегда отдают в JSON. Так выглядит ответ на запрос пользователя:
{
"id": 42,
"login": "anna_dev",
"email": "anna@example.com",
"is_active": true,
"roles": ["user", "editor"]
}Если синтаксис JSON пока непривычен, загляните в отдельный разбор формата JSON и работы с ним: там про типы данных, ошибки парсинга и модуль json в Python.
Как отправить первый запрос к API: пошагово
Для тренировки подойдут открытые API без регистрации. GitHub API отдаёт публичные данные без ключа (с лимитом 60 запросов в час на IP), а JSONPlaceholder - учебный сервис с фейковыми постами, который принимает и POST.
Шаг 1. curl в терминале
curl есть в Linux, macOS и в Windows 10/11. Получаем профиль пользователя:
curl https://api.github.com/users/octocatСоздаём запись методом POST с JSON в теле (в Linux и macOS):
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H "Content-Type: application/json" \
-d '{"title": "test", "body": "hello", "userId": 1}'Сервер ответит кодом 201 и вернёт объект с присвоенным id. Данные на самом деле не сохраняются, сервис только имитирует создание.
Шаг 2. Python и библиотека requests
Установите библиотеку командой pip install requests, лучше внутри виртуального окружения:
import requests
r = requests.get("https://api.github.com/users/octocat", timeout=10)
r.raise_for_status() # бросит исключение на 4xx и 5xx
user = r.json() # JSON -> словарь Python
print(user["login"], user["public_repos"])Шаг 3. JavaScript и fetch
Тот же запрос из браузера или Node.js 18+:
const res = await fetch("https://api.github.com/users/octocat");
if (!res.ok) throw new Error("HTTP " + res.status);
const user = await res.json();
console.log(user.login, user.public_repos);Обратите внимание: fetch не считает 404 или 500 ошибкой и не бросает исключение. Проверять res.ok нужно самому.
Ключи, токены и лимиты запросов
Большинство полезных API требуют авторизацию. Сервис должен понимать, кто к нему пришёл, чтобы считать лимиты и выставлять счета. Встречаются три основных варианта:
- API-ключ - длинная строка, которую выдают в личном кабинете. Передаётся в заголовке или параметре запроса.
- Bearer-токен - заголовок
Authorization: Bearer <токен>. Часто живёт ограниченное время. - OAuth 2.0 - пользователь сам разрешает приложению доступ к своим данным, приложение получает токен. Так работает вход через внешние аккаунты.
Почти у каждого API есть лимиты (rate limit): сколько запросов можно сделать за минуту или час. При превышении сервер отвечает кодом 429 Too Many Requests, иногда с заголовком Retry-After, где указано, сколько секунд подождать.
Никогда не пишите ключ прямо в коде. Положите его в переменную окружения или файл .env, добавьте .env в .gitignore и читайте через os.environ["API_KEY"]. Ключи, случайно отправленные в публичный репозиторий, боты находят за минуты. Если это уже случилось, сразу отзовите ключ в кабинете сервиса: удаление коммита не помогает, история остаётся.
Как устроены коммиты и почему из истории ничего не пропадает, хорошо видно в шпаргалке по командам Git.
Типичные ошибки новичка при работе с API
- Путают 401 и 403. 401 - сервер не понял, кто вы: токена нет или он просрочен. 403 - сервер понял, кто вы, но прав не хватает.
- Забывают заголовок Content-Type. Без
application/jsonсервер может не распознать тело и вернуть 400 или 415. В requests используйте параметрjson=вместоdata=: он сам сериализует словарь и выставит заголовок. - Не ставят таймаут. В requests по умолчанию таймаута нет, и скрипт может висеть бесконечно, если сервер не отвечает.
- Сталкиваются с CORS и думают, что API сломан. Браузер блокирует запросы к чужому домену, если сервер их явно не разрешил. Из curl или Python тот же запрос работает. Решается на стороне сервера или через собственный бэкенд-прокси.
- Не читают документацию. Формат дат, пагинация, обязательные поля - всё это описано в доках. У многих API есть интерактивная документация Swagger UI, где запрос можно отправить прямо со страницы.
- Обращаются к полям без проверки. Если API вернул ошибку, в JSON не будет ожидаемых ключей, и код упадёт с KeyError. Сначала проверяйте код ответа.
Чем тестировать API и как тренироваться
Для ручных запросов кроме curl удобны программы с интерфейсом: Postman, Insomnia, Bruno. Они сохраняют коллекции запросов, подставляют переменные окружения и красиво показывают JSON. Ещё один вариант - расширения для VS Code вроде REST Client или Thunder Client: запросы пишутся в обычном текстовом файле рядом с кодом.
Лучший способ понять API - написать своё. На Python это делается за вечер с FastAPI или Flask:
from fastapi import FastAPI
app = FastAPI()
@app.get("/hello/{name}")
def hello(name: str):
return {"message": f"Привет, {name}!"}Запуск: pip install "fastapi[standard]", затем fastapi dev main.py. По адресу http://127.0.0.1:8000/docs FastAPI сам построит интерактивную документацию в формате OpenAPI. Дальше можно добавить базу данных, POST-эндпоинт и коды ошибок, а потом упаковать сервис в контейнер по гайду Docker для начинающих. Больше материалов по языку собрано в разделе Python.