Какие знаешь виды API?

Виды API (Application Programming Interfaces)

API — это интерфейс взаимодействия между программами. В системном анализе мы различаем API по архитектурному стилю, протоколу, области применения и методу коммуникации.

1. REST API (Representational State Transfer)

Определение: Architectural style для построения web сервисов, основанный на HTTP и стандартных операциях CRUD (Create, Read, Update, Delete).

Характеристики:

• Использует HTTP методы: GET (чтение), POST (создание), PUT/PATCH (обновление), DELETE (удаление)
• Ресурсы идентифицируются URLs
• Stateless (каждый запрос независим)
• Кешируемость (GET запросы могут кешироваться)

Пример из практики:

GET /api/v1/orders           → Получить все заказы
GET /api/v1/orders/123       → Получить заказ с ID 123
POST /api/v1/orders          → Создать новый заказ
PUT /api/v1/orders/123       → Обновить заказ 123 полностью
PATCH /api/v1/orders/123     → Частичное обновление заказа
DELETE /api/v1/orders/123    → Удалить заказ 123

Пример запроса:

POST /api/v1/orders HTTP/1.1
Host: api.logistics.com
Content-Type: application/json
Authorization: Bearer token123

{
  "user_id": "f47ac10b-58cc",
  "items": [{"product_id": "p1", "quantity": 2}],
  "delivery_address": "Moscow, Kremlin"
}

Ответ (201 Created):
{
  "id": "order-789",
  "status": "created",
  "created_at": "2025-03-28T10:30:00Z"
}

Плюсы:

• Простой и понятный
• Широкая поддержка (браузеры, инструменты, библиотеки)
• Кешируемость улучшает производительность
• Stateless облегчает масштабирование

Минусы:

• Overfetching (получаешь больше данных, чем нужно)
• Underfetching (нужно несколько запросов для полной информации)
• N+1 проблема (нужны дополнительные запросы для связанных данных)

Когда использую:

• Простые CRUD операции
• Публичные API
• Когда данные структурированы

2. GraphQL

Определение: Query language для API, который позволяет клиенту запросить ровно те данные, которые ему нужны.

Характеристики:

• Единая endpoint: обычно /graphql
• Клиент определяет структуру ответа
• Strongly typed schema
• Поддержка Real-time подписок (subscriptions)

Пример из практики:

# Запрос: получить заказ с информацией о пользователе и товарах
query GetOrder($orderId: ID!) {
  order(id: $orderId) {
    id
    status
    user {
      name
      email
    }
    items {
      product {
        name
        price
      }
      quantity
    }
  }
}

# Ответ содержит ровно запрошенные поля
{
  "data": {
    "order": {
      "id": "order-789",
      "status": "pending",
      "user": {
        "name": "Ivan",
        "email": "ivan@example.com"
      },
      "items": [{...}]
    }
  }
}

Плюсы:

• Нет overfetching / underfetching
• Одна точка входа (проще управлять версионированием)
• Introspection (клиент может узнать структуру API)
• Хорошо для mobile (экономит трафик)

Минусы:

• Сложнее для простых случаев
• Требует специальные инструменты
• Harder to cache (все POST запросы)
• N+1 проблема требует специальных решений (DataLoader)

Когда использую:

• Complex data relationships
• Mobile приложения (экономия трафика)
• Несколько клиентов с разными потребностями в данных

3. gRPC (gRPC Remote Procedure Call)

Определение: High-performance RPC framework использующий HTTP/2 и Protocol Buffers.

Характеристики:

• Binary protocol (более эффективный чем JSON)
• HTTP/2 multiplexing (параллельные запросы в одном соединении)
• Bi-directional streaming (клиент и сервер могут отправлять данные одновременно)
• Strongly typed (Protocol Buffers)

Пример из практики:

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (stream Order);
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

message Order {
  string id = 1;
  string status = 2;
  repeated Item items = 3;
}

Плюсы:

• Очень быстро (binary + HTTP/2)
• Streaming поддержка (для больших данных)
• Strongly typed schema (Protocol Buffers)
• Хорошо для микросервисов
• Меньше payload (экономия трафика)

Минусы:

• Не простой для веб-браузеров (нужен gRPC-Web)
• Сложнее для отладки (binary формат)
• Требует специальные инструменты
• Не годится для простых случаев

Когда использую:

• Коммуникация между микросервисами
• Real-time приложения (streaming)
• High-load системы
• Когда важна производительность

4. SOAP (Simple Object Access Protocol)

Определение: Previous generation web service protocol, основанный на XML. Сейчас используется реже.

Характеристики:

• XML format
• WSDL (Web Services Description Language) для описания
• Envelope structure
• ACID транзакции

Пример:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap-envelope/">
  <soap:Body>
    <m:CreateOrder xmlns:m="http://logistics.com/api">
      <order>
        <userId>123</userId>
        <amount>1000</amount>
      </order>
    </m:CreateOrder>
  </soap:Body>
</soap:Envelope>

Плюсы:

• Стандартизированный формат
• Поддержка ACID
• Хорошая для enterprise систем

Минусы:

• Тяжелый (много XML)
• Сложный для клиента
• Медленнее чем REST/gRPC
• Legacy technology (новые проекты не используют)

Когда использую:

• Интеграция с legacy системами
• Когда требуются ACID гарантии
• Enterprise интеграция (корпоративные партнёры)

5. Webhook

Определение: Callback механизм, когда сервер отправляет HTTP запрос клиенту при возникновении события.

Характеристики:

• Асинхронная коммуникация
• Event-driven
• Клиент предоставляет URL для callback'а

Пример из практики:

Шаг 1: Клиент регистрирует webhook
POST /api/v1/webhooks
{
  "event": "order.completed",
  "url": "https://client.com/webhooks/order-completed"
}

Шаг 2: Когда заказ завершён, сервер отправляет
POST https://client.com/webhooks/order-completed
{
  "event": "order.completed",
  "data": {
    "order_id": "order-789",
    "status": "completed",
    "completed_at": "2025-03-28T15:30:00Z"
  }
}

Плюсы:

• Асинхронная обработка
• Real-time уведомления
• Клиент не должен полировать (pull) данные
• Экономия ресурсов

Минусы:

• Сложность с retry logic
• Гарантия доставки (at-least-once / exactly-once?)
• Клиент должен быть доступен
• Debugging сложнее

Когда использую:

• Event-driven архитектура
• Real-time уведомления
• Third-party интеграции (Payment gateway → уведомления)

6. Message Queue / Event Streaming

Определение: Asynchronous communication через очередь сообщений (RabbitMQ, Kafka, etc.)

Характеристики:

• Асинхронная доставка
• Гарантия доставки
• Множество subscribers
• Persistence

Пример из практики:

Процесс создания заказа в микросервисной архитектуре:

OrderService (Producer)
    ↓
[RabbitMQ / Kafka]
    ↓
PaymentService (Consumer) → обработка платежа
InventoryService (Consumer) → проверка запасов
NotificationService (Consumer) → отправка email
AnalyticsService (Consumer) → запись в аналитику

Плюсы:

• Полная асинхронность
• Decoupling между сервисами
• Гарантия доставки
• Масштабируемость

Минусы:

• Сложность: eventual consistency
• Требует брокер (инфраструктура)
• Debugging сложнее
• Требует обработка ошибок и retry

Когда использую:

• Микросервисная архитектура
• Когда нужна высокая пропускная способность
• Event-driven системы

7. WebSocket

Определение: Bi-directional communication protocol с persistent connection.

Характеристики:

• Persistent TCP connection
• Low latency
• Полная duplex (клиент и сервер могут отправлять одновременно)
• Real-time

Пример из практики:

// Клиент
const socket = new WebSocket('wss://api.logistics.com/ws');
socket.onopen = () => {
  socket.send(JSON.stringify({action: 'subscribe_order', orderId: '123'}));
};
socket.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Заказ обновлён:', update); // Real-time обновление
};

// Сервер может отправить несколько обновлений
{"status": "shipped", "timestamp": "10:30"}
{"status": "in_delivery", "timestamp": "14:15"}
{"status": "delivered", "timestamp": "16:45"}

Плюсы:

• Real-time bi-directional
• Low latency
• Persistent connection экономит на overhead
• Идеально для live updates

Минусы:

• Требует статeful соединение (сложнее масштабировать)
• Firewall/proxy проблемы
• Memory usage на сервере
• Сложнее с load balancing

Когда использую:

• Real-time приложения (чат, live tracking)
• Live notifications
• Collaborative editing

8. Server-Sent Events (SSE)

Определение: One-directional push from server to client через HTTP.

Характеристики:

• Server инициирует push
• Text-based (проще чем WebSocket)
• HTTP protocol (проще с proxies)
• Автоматический reconnect

Пример:

const eventSource = new EventSource('/api/v1/order/123/track');
eventSource.addEventListener('location_update', (event) => {
  const location = JSON.parse(event.data);
  console.log('Текущее положение:', location.lat, location.lng);
});

Плюсы:

• Проще чем WebSocket
• Встроен в браузеры
• Автоматический reconnect
• Хорошо для notifications

Минусы:

• Только server → client (не bi-directional)
• Статeful соединение (проблемы масштабирования)
• Ограничение открытых соединений (браузеры: 6 per origin)

Когда использую:

• One-way notifications (push)
• Live updates (но не нужна клиент-сервер коммуникация)
• Простые real-time случаи

Сравнительная таблица

Моя практика выбора API

В системе логистики я использовал комбинацию:

1. REST API для public endpoints (мобильное приложение, веб-клиенты)
2. gRPC для internal communication между микросервисами
3. WebSocket для real-time tracking доставки
4. Message Queue (Kafka) для асинхронной обработки событий
5. Webhook для интеграции с платежной системой и курьерскими сервисами

Этот подход обеспечил оптимальный баланс между простотой, производительностью и масштабируемостью.