Чтение документации API

Ты знаешь REST-принципы, JSON и CRUD. Но как узнать, какие эндпоинты есть у конкретного API? Какие параметры передавать? Что вернёт сервер? Всё это описано в документации API. Умение читать API-доку — один из главных навыков разработчика.

Где найти документацию API

Публичные API всегда имеют документацию. Ищи её по шаблону: {сервис} API docs или {сервис} developer. Примеры:

Для внутренних API компании документация обычно лежит во внутренней wiki, Swagger UI или Postman-коллекциях.

Структура API-документации

Хорошая документация содержит:

Base URL. Корень всех эндпоинтов: https://api.example.com/v1/
Аутентификация. Как получить ключ и как его передавать (заголовок Authorization, query-параметр, cookie).
Эндпоинты. Список доступных URL с методами (GET/POST/PUT/DELETE).
Формат запроса. Какие параметры (path, query, body), их типы, обязательность.
Формат ответа. Пример успешного ответа и возможных ошибок.
Коды ошибок. Что означает 400, 401, 403, 404, 429, 500 для этого API.

Читаем документацию: пример

Возьмём документацию GitHub API для получения информации о пользователе:

GET /users/{username}

Параметры:
  username (path, required, string) — логин пользователя GitHub

Ответ 200 OK:
  {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://avatars.githubusercontent.com/u/1",
    "name": "The Octocat",
    "company": "@github",
    "blog": "https://github.blog",
    "location": "San Francisco",
    "public_repos": 8,
    "followers": 20,
    "following": 0
  }

Ошибки:
  404 — пользователь не найден
  403 — превышен rate limit (60 запросов/час без авторизации)

Из документации мы понимаем:

Эндпоинт: GET /users/{username}, где {username} — подстановка логина.
Возвращает JSON-объект с полями пользователя.
Без авторизации лимит 60 запросов в час.

Переводим в вызов fetch():

fetch('https://api.github.com/users/octocat')
  .then(r => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  })
  .then(user => console.log(user.login, user.public_repos));

OpenAPI / Swagger: машиночитаемая документация

Часто документация представлена не просто текстом, а в формате OpenAPI (бывший Swagger). Это JSON/YAML-файл, описывающий все эндпоинты, параметры и ответы. На его основе генерируется интерактивный UI, где можно прямо в браузере вызвать API и посмотреть ответ:

Swagger UI:
  GET /users/{id}
  [Try it out] → ввести id=42 → Execute → видим JSON-ответ

Swagger UI — мощный инструмент для изучения API. Не нужно писать код, чтобы проверить, как работает эндпоинт. Часто доступен по адресу /api/docs или /swagger.

Тестирование API без кода

Два главных инструмента для ручного тестирования API:

1. curl — консольная утилита, отправляющая HTTP-запросы:

# GET-запрос
curl https://api.github.com/users/octocat

# POST с JSON
curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"name": "тест"}'

# Показать заголовки ответа
curl -I https://example.com

2. Postman / Bruno / Hoppscotch — графические клиенты API. Позволяют сохранять запросы в коллекции, настраивать окружения (dev/staging/prod), писать автотесты на JavaScript.

Rate Limiting: важный раздел документации

Публичные API всегда ограничивают количество запросов. Rate limit указывается в документации:

GitHub без авторизации: 60 запросов/час.
GitHub с токеном: 5000 запросов/час.
OpenWeatherMap бесплатный: 60 запросов/минуту.

Сервер возвращает специальные заголовки с информацией о лимите:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1714500000

Клиент должен проверять эти заголовки и замедляться, когда лимит подходит к концу. При превышении лимита — 429 Too Many Requests.

Версионирование API

API со временем меняется. Чтобы не ломать существующих клиентов, используют версионирование. Три распространённых подхода:

В URL:    https://api.example.com/v1/users           (самый популярный)
В заголовке:  Accept: application/vnd.example.v2+json  (GitHub)
В query:  https://api.example.com/users?version=2      (реже)

Новая версия API может добавлять поля ответа, но не удалять существующие поля или менять их смысл — это нарушит обратную совместимость.

Проверь себя

Где в документации API искать base URL?
Что такое Swagger UI и зачем он нужен?
Как узнать, сколько запросов ещё можно сделать до превышения rate limit?

<details> <summary>Ответы</summary>

Обычно в самом начале документации, в разделе «Getting Started» или «Overview». Это корневой URL всех эндпоинтов, например https://api.example.com/v1/.
Swagger UI — интерактивная документация, сгенерированная из OpenAPI-спецификации. Позволяет вызвать любой эндпоинт прямо в браузере и увидеть ответ.
Из заголовков ответа: X-RateLimit-Remaining (осталось), X-RateLimit-Limit (всего), X-RateLimit-Reset (когда сбросится). Или из документации.

</details>

Что унести с урока

Документация API: base URL, эндпоинты, параметры запроса, формат ответа, коды ошибок, аутентификация.
Swagger UI позволяет тестировать API в браузере, не написав кода.
curl, Postman, Bruno — инструменты для ручного тестирования API.
Rate limiting и версионирование — важные аспекты, которые всегда описаны в документации.

Модуль «Основы REST API» завершён. Мы разобрали, как программы общаются друг с другом через HTTP и JSON. Но REST — это request-response: клиент всегда инициатор. В следующем модуле разберём WebSockets — технологию, которая позволяет серверу отправлять данные клиенту самому в реальном времени.

Чтение документации API