Разработка API: что такое API, как создать и задокументировать

API (Application Programming Interface) — это интерфейс, через который программы общаются друг с другом. Когда мобильное приложение получает список товаров, когда сайт показывает погоду, когда CRM синхронизируется с почтой — всё это работает через API. Сегодня API — основа любой цифровой инфраструктуры: от мессенджеров до банков.

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

Что такое API и зачем оно нужно

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

Зачем нужно API:

• Разделение фронтенда и бэкенда. React-приложение, мобильное приложение и десктопный клиент могут использовать одно и то же API — не нужно дублировать логику.
• Интеграции. Подключить платёжную систему, карты, сервис рассылок, CRM — всё это делается через их API.
• Микросервисы. Независимые сервисы общаются между собой через API.
• Партнёрские интеграции. Дать другим компаниям доступ к вашим данным или функциям — через публичное API.

«Хорошее API — как хороший инструмент: его логика очевидна, поведение предсказуемо, и ты забываешь, что пользуешься инструментом. Плохое API постоянно о себе напоминает.»

Виды API

REST API

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

Принципы REST:

• Единообразие интерфейса — предсказуемые URL и методы
• Stateless — каждый запрос самодостаточен, сервер не хранит состояние сессии
• Клиент-сервер — чёткое разделение ответственности
• Кэшируемость — ответы могут кэшироваться

HTTP-статусы ответа:

• 200 OK — успешно
• 201 Created — создано
• 400 Bad Request — ошибка в запросе клиента
• 401 Unauthorized — не авторизован
• 403 Forbidden — нет прав
• 404 Not Found — не найдено
• 422 Unprocessable Entity — ошибка валидации
• 500 Internal Server Error — ошибка сервера

GraphQL

Язык запросов для API, разработанный Meta. Клиент сам описывает, какие именно данные ему нужны.

Главное отличие от REST: в REST каждый эндпоинт возвращает фиксированную структуру. В GraphQL один эндпоинт (/graphql), и клиент запрашивает именно те поля, которые нужны.

# Клиент запрашивает только нужные поля
query {
  user(id: "42") {
    name
    email
    orders {
      id
      total
    }
  }
}

Когда выбирать GraphQL:

• Сложные данные с множеством связей
• Несколько клиентов с разными потребностями (веб, мобильный)
• Нужно избежать over-fetching (лишних данных) и under-fetching (недостающих данных)

Когда REST лучше:

• Простые CRUD-операции
• Публичное API для третьих разработчиков
• Кэширование критично (GraphQL сложнее кэшировать)

gRPC

Высокопроизводительный RPC-фреймворк от Google. Использует Protocol Buffers (бинарный формат) вместо JSON — значительно быстрее и легче.

Когда использовать: межсервисное взаимодействие в микросервисной архитектуре, высоконагруженные системы, где важна скорость.

WebSocket API

Двустороннее соединение в реальном времени. В отличие от REST, где клиент всегда инициирует запрос, WebSocket позволяет серверу отправлять данные клиенту без запроса.

Используется в: чатах, live-уведомлениях, онлайн-играх, трекинге в реальном времени, совместном редактировании.

Проектирование REST API: лучшие практики

Именование эндпоинтов

# Хорошо — существительные, множественное число, иерархия
GET    /api/v1/users
GET    /api/v1/users/42
GET    /api/v1/users/42/orders
POST   /api/v1/users
DELETE /api/v1/users/42

# Плохо — глаголы в URL
GET /api/getUsers
POST /api/createUser
GET /api/getUserOrders?userId=42

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

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

/api/v1/users  — текущая версия
/api/v2/users  — новая версия с изменениями

Пагинация

При возврате списков всегда используйте пагинацию:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 347,
    "total_pages": 18
  }
}

Фильтрация и сортировка

GET /api/v1/orders?status=pending&sort=created_at&order=desc
GET /api/v1/products?category=electronics&min_price=1000&max_price=50000

Структура ответа

Единообразная структура ответов упрощает работу клиентам:

// Успешный ответ
{
  "success": true,
  "data": {
    "id": 42,
    "name": "Иван Иванов",
    "email": "ivan@example.com"
  }
}

// Ответ с ошибкой
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email уже используется",
    "fields": {
      "email": "Пользователь с таким email уже существует"
    }
  }
}

Авторизация и аутентификация API

API Keys

Простейший способ: клиент передаёт статичный ключ в заголовке.

Authorization: ApiKey sk_live_abc123xyz

Подходит для: серверных интеграций, простых публичных API.

Не подходит для: пользовательской аутентификации.

JWT (JSON Web Tokens)

Стандарт для аутентификации пользователей. Токен содержит данные пользователя и подписан секретным ключом сервера.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Поток аутентификации:

1. Пользователь вводит логин/пароль
2. Сервер проверяет и возвращает access_token (короткоживущий) и refresh_token (долгоживущий)
3. Клиент отправляет access_token в заголовке каждого запроса
4. Когда access_token истекает — обновляет его через refresh_token

OAuth 2.0

Стандарт для делегированного доступа. «Войти через Google / ВКонтакте» — это OAuth 2.0. Пользователь даёт вашему приложению доступ к данным стороннего сервиса.

Разработка API на практике

Пример простого REST API на FastAPI (Python)

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI(title="Users API", version="1.0.0")

# Модель данных
class User(BaseModel):
    id: int
    name: str
    email: str

class UserCreate(BaseModel):
    name: str
    email: str

# Имитация базы данных
users_db = [
    User(id=1, name="Иван Иванов", email="ivan@example.com"),
    User(id=2, name="Мария Петрова", email="maria@example.com"),
]

# Получить всех пользователей
@app.get("/api/v1/users", response_model=List[User])
def get_users():
    return users_db

# Получить пользователя по ID
@app.get("/api/v1/users/{user_id}", response_model=User)
def get_user(user_id: int):
    user = next((u for u in users_db if u.id == user_id), None)
    if not user:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    return user

# Создать пользователя
@app.post("/api/v1/users", response_model=User, status_code=201)
def create_user(user_data: UserCreate):
    new_user = User(
        id=len(users_db) + 1,
        name=user_data.name,
        email=user_data.email
    )
    users_db.append(new_user)
    return new_user

FastAPI автоматически генерирует интерактивную документацию по этому коду — доступна на /docs.

Документация API

Хорошая документация — обязательная часть API. Без неё разработчики не смогут интегрироваться.

OpenAPI / Swagger

Стандарт описания REST API в формате YAML или JSON. Большинство современных фреймворков генерируют OpenAPI-схему автоматически.

Swagger UI — интерактивная документация, которая позволяет отправлять запросы прямо из браузера. FastAPI генерирует её автоматически на /docs.

Что должна содержать документация

• Описание каждого эндпоинта: что делает, какие параметры принимает
• Примеры запросов и ответов
• Описание всех полей с типами и ограничениями
• Коды ошибок и их значения
• Руководство по аутентификации
• Примеры интеграции на популярных языках

Инструменты документирования

• Swagger / OpenAPI — стандарт для REST API. Автогенерация через FastAPI, Spring, NestJS.
• Postman — инструмент для тестирования и документирования API. Коллекции Postman можно публиковать как документацию.
• Redoc — красивый UI для отображения OpenAPI-схемы. Альтернатива Swagger UI.
• Stoplight — платформа для дизайна и документирования API.

Тестирование API

Ручное тестирование

Postman — инструмент №1 для тестирования API. Сохраняйте запросы в коллекции, настраивайте окружения (dev/staging/prod), пишите тесты прямо в интерфейсе.

Insomnia — альтернатива Postman, часто удобнее для GraphQL.

curl — утилита командной строки для HTTP-запросов:

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

# POST-запрос с JSON-телом
curl -X POST https://api.example.com/api/v1/users   -H "Content-Type: application/json"   -H "Authorization: Bearer TOKEN"   -d '{"name": "Иван", "email": "ivan@example.com"}'

Автоматическое тестирование

Автотесты API проверяют, что эндпоинты возвращают правильные данные при правильных и неправильных входных данных.

# Пример теста на pytest + httpx
import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_get_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/api/v1/users/1")

    assert response.status_code == 200
    data = response.json()
    assert data["id"] == 1
    assert "email" in data

@pytest.mark.asyncio
async def test_get_nonexistent_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/api/v1/users/9999")

    assert response.status_code == 404

Безопасность API

• Rate Limiting — ограничение числа запросов от одного клиента. Защищает от DDoS и брутфорса. Например: не более 100 запросов в минуту на IP.
• Валидация входных данных — никогда не доверяйте тому, что присылает клиент. Проверяйте типы, длины, форматы, допустимые значения.
• HTTPS — всегда. HTTP для API — недопустимо в продакшне.
• CORS — настройте список разрешённых источников. Wildcard * допустим только для публичных API без аутентификации.
• Логирование — записывайте все запросы (без чувствительных данных) для аудита и отладки.

Итог

API — основа современной разработки. REST остаётся стандартом для большинства проектов, GraphQL — для сложных данных с множеством клиентов, gRPC — для высокопроизводительных межсервисных взаимодействий.

Хорошее API: предсказуемое, задокументированное, версионированное, безопасное и быстрое. Инвестиция в качество API окупается каждый раз, когда разработчик интегрируется с ним без вопросов.

Источники

• OpenAPI Specification
• FastAPI — документация
• GraphQL — официальный сайт
• Postman — документация
• OWASP API Security Top 10