Что такое API: простое объяснение для начинающих

Введение

Когда вы заходите в приложение погоды и видите актуальный прогноз — это работает API. Когда сайт предлагает войти через Google — тоже API. Когда интернет-магазин принимает оплату картой — снова API.

API (Application Programming Interface) — это интерфейс взаимодействия между программами. Он позволяет одному приложению запрашивать данные или функциональность у другого по заранее определённым правилам.

В этой статье разберём, что такое API, как он устроен и как начать его использовать в своих проектах.

Аналогия из реальной жизни

Представьте ресторан. Вы — клиент, кухня — сервер с данными. Вы не идёте на кухню сами — вы делаете заказ через официанта. Официант передаёт заказ на кухню, получает блюдо и приносит вам.

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

Как работает HTTP API

Большинство современных API работают по протоколу HTTP. Клиент отправляет запрос на определённый адрес (endpoint), сервер обрабатывает его и возвращает ответ — обычно в формате JSON.

Основные HTTP-методы:

• GET — получить данные
• POST — создать новую запись
• PUT / PATCH — обновить запись
• DELETE — удалить запись

Пример запроса к публичному API для получения информации о пользователе:

GET https://api.github.com/users/torvalds

Ответ сервера (сокращённо):

{
  "login": "torvalds",
  "name": "Linus Torvalds",
  "public_repos": 7,
  "followers": 230000
}

Первый запрос к API на JavaScript

Сделаем запрос к бесплатному публичному API. Используем fetch — встроенный инструмент браузера и Node.js:

// Получаем список постов с тестового API
async function getPosts() {
  // Отправляем GET-запрос
  const response = await fetch('https://jsonplaceholder.typicode.com/posts');

  // Проверяем, что сервер ответил успехом
  if (!response.ok) {
    throw new Error(`Ошибка сервера: ${response.status}`);
  }

  // Парсим JSON из тела ответа
  const posts = await response.json();

  console.log(`Получено постов: ${posts.length}`);
  console.log('Первый пост:', posts[0]);
}

getPosts();

Запрос с телом — создаём новый пост через POST:

async function createPost(title, body) {
  const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
    method: 'POST',
    // Указываем формат данных в заголовке
    headers: {
      'Content-Type': 'application/json',
    },
    // Преобразуем объект в строку JSON
    body: JSON.stringify({
      title: title,
      body: body,
      userId: 1,
    }),
  });

  const newPost = await response.json();
  console.log('Созданный пост:', newPost);
}

createPost('Мой первый пост', 'Текст поста через API');

Авторизация в API

Многие API требуют авторизацию — чтобы знать, кто делает запрос и какие права у этого пользователя. Самый распространённый способ — API-ключ или Bearer-токен в заголовке:

async function getUserData(token) {
  const response = await fetch('https://api.example.com/me', {
    headers: {
      // Передаём токен в заголовке Authorization
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
  });

  if (response.status === 401) {
    throw new Error('Токен недействителен или истёк');
  }

  return response.json();
}

API-ключ обычно получают при регистрации на платформе и хранят в переменных окружения — никогда не вшивают в код напрямую:

// Правильно — из переменных окружения
const API_KEY = process.env.MY_API_KEY;

// Неправильно — секрет в коде попадёт в репозиторий
const API_KEY = 'sk-abc123supersecret';

Коды ответов HTTP

Сервер всегда возвращает числовой код, который показывает результат запроса:

Всегда проверяйте код ответа перед работой с данными — не рассчитывайте, что запрос всегда успешен.

Что такое REST API

REST (Representational State Transfer) — набор архитектурных принципов для построения API. Большинство современных веб-API следуют именно REST-подходу.

Главные принципы REST:

• Ресурсы в URL — /users, /posts/42, /orders/5/items
• Методы отражают действие — GET /users читает, POST /users создаёт
• Без состояния — каждый запрос самодостаточен, сервер не помнит предыдущих
• Единообразный интерфейс — предсказуемая структура URL и ответов

Пример REST-маршрутов для ресурса articles:

GET    /articles        — список всех статей
GET    /articles/42     — статья с id=42
POST   /articles        — создать статью
PUT    /articles/42     — полностью обновить статью 42
PATCH  /articles/42     — частично обновить статью 42
DELETE /articles/42     — удалить статью 42

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

Не обрабатывать ошибки сети. fetch не выбрасывает исключение при HTTP-ошибках (400, 500) — только при проблемах сети. Всегда проверяйте response.ok.

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

Игнорировать лимиты. Большинство API ограничивают количество запросов в единицу времени (rate limiting). При коде 429 делайте паузу перед повторной попыткой.

Парсить JSON без проверки. Если сервер вернул не JSON (например, HTML страницу ошибки), response.json() выбросит исключение. Оборачивайте в try/catch.

async function safeRequest(url) {
  try {
    const response = await fetch(url);

    if (!response.ok) {
      // Не пытаемся парсить тело при ошибке сервера
      throw new Error(`HTTP ошибка: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    // Ловим и сетевые ошибки, и ошибки парсинга
    console.error('Запрос не удался:', error.message);
    return null;
  }
}

Заключение

API — фундаментальный инструмент современной разработки. Понимание того, как работают HTTP-запросы, методы, заголовки и коды ответов, открывает доступ к тысячам готовых сервисов: платёжные системы, карты, соцсети, погода, нейросети.

Следующий шаг — попрактикуйтесь с публичными API без регистрации: JSONPlaceholder для CRUD-операций или Open-Meteo для погодных данных. Затем изучите документацию любого сервиса, которым пользуетесь — почти у каждого есть API.