раздел 06 · подстраница 1

API: как программы обмениваются данными

API звучит как что-то сложное, но идея проста: это меню в ресторане. Вы не идёте на кухню готовить сами - вы делаете заказ по меню и получаете блюдо. API - это меню сервера: список того, что у него можно попросить, и в каком виде он ответит.

Запрос и ответ

Любое общение с API - это пара: вы отправляете запрос (request), сервер присылает ответ (response). Запрос едет по протоколу HTTP - тому же, по которому открываются сайты.

Запрос:  GET https://api.example.com/tasks
Ответ:   [ { "id": 1, "text": "купить молоко", "done": false } ]

Вы попросили список задач по адресу /tasks - сервер вернул его в виде JSON.

Методы: GET, POST и компания

У запроса есть «глагол» - что именно вы хотите сделать:

  • GET - получить данные. «Дай мне список задач».
  • POST - создать новое. «Добавь вот эту задачу».
  • PUT / PATCH - изменить существующее. «Отметь задачу 1 выполненной».
  • DELETE - удалить. «Убери задачу 3».

Заметили совпадение? Это те же действия, что и в базе (SELECT / INSERT / UPDATE / DELETE), только через сеть. API - это, по сути, вежливая дверь к данным.

GET    /tasks        -> получить все задачи
POST   /tasks        -> создать задачу (данные в теле запроса, JSON)
PATCH  /tasks/1      -> изменить задачу с id=1
DELETE /tasks/1      -> удалить задачу с id=1

Как это выглядит из браузера

Фронтенд просит данные функцией fetch. Получает JSON, превращает в объект, рисует на странице.

// получить список задач
const res = await fetch("/api/tasks");
const tasks = await res.json();   // JSON-текст -> объект
renderTasks(tasks);

// создать новую задачу
await fetch("/api/tasks", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "сдать отчёт" }),  // объект -> JSON-текст
});

Вот и весь цикл: данные хранятся в базе на сервере, бэкенд достаёт их и отдаёт как JSON, фронтенд получает и показывает. JSON здесь - язык обмена.

Коды ответов

Сервер вместе с данными присылает трёхзначный код - статус запроса. Знать главные полезно:

  • 200 - всё хорошо, вот данные;
  • 201 - создано (после успешного POST);
  • 400 - вы прислали что-то не то (ошибка в запросе);
  • 401 / 403 - не авторизованы / нет прав;
  • 404 - не найдено (такого адреса или записи нет);
  • 500 - сломалось на сервере.

Чужие API

Тот же механизм работает с внешними сервисами: погода, карты, оплата, нейросети. Вы шлёте запрос на их адрес - получаете JSON. Обычно нужен ключ доступа (API key), который вы передаёте в запросе, чтобы сервис знал, кто вы.

import requests

res = requests.get(
    "https://api.example.com/weather",
    params={"city": "Moscow"},
    headers={"Authorization": "Bearer ВАШ_КЛЮЧ"},
)
data = res.json()
print(data["temperature"])

Как посмотреть API своими глазами

  • открыть GET-адрес прямо в браузере - простой ответ покажется как есть;
  • Postman или Insomnia - программы, где удобно слать любые запросы и смотреть ответы;
  • вкладка Network в инструментах разработчика браузера (F12) - показывает все запросы, что шлёт ваш фронтенд, и ответы на них. Лучший способ понять, что реально происходит.

Антипаттерны

  • Класть API-ключи в код и в git. Только переменные окружения.
  • Не проверять код ответа. Запрос мог упасть с 404 или 500, а вы пытаетесь читать данные из пустого ответа.
  • Ходить из браузера прямо в чужой платный API с секретным ключом. Ключ утечёт в код страницы. Такие запросы делает бэкенд, а не фронтенд.
  • Путать «нет данных» и «ошибка». Пустой список (200 и []) - это не то же самое, что упавший запрос (500). Обрабатывайте отдельно.