Расскажи про свой опыт работы с API

Мой опыт работы с API

Введение

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

Области моего опыта с API

1. Design и Specification API

Мой процесс проектирования:

Шаг 1: Определить endpoints
- Какие ресурсы нужно expose?
- Какие операции необходимы?
- Какой HTTP метод для каждой операции?

Пример (система логистики):
GET    /api/v1/orders             → Получить список
GET    /api/v1/orders/{id}        → Получить один
POST   /api/v1/orders             → Создать
PATCH  /api/v1/orders/{id}        → Обновить
DELETE /api/v1/orders/{id}        → Удалить
GET    /api/v1/orders/{id}/items  → Вложенный ресурс

Шаг 2: Определить payload
- Какие fields в request?
- Какие fields в response?
- Какие поля required, какие optional?

Пример request:
{
  "customer_id": "uuid" (required),
  "items": [{"product_id": "uuid", "quantity": 2}] (required),
  "delivery_address": "string" (required),
  "notes": "string" (optional),
  "insurance": boolean (optional, default: false)
}

Пример response:
{
  "id": "uuid",
  "customer_id": "uuid",
  "items": [...],
  "status": "created",
  "total_amount": 1500.50,
  "created_at": "2025-03-28T10:30:00Z",
  "updated_at": "2025-03-28T10:30:00Z"
}

Шаг 3: Определить error responses
- 400 Bad Request (validation error)
- 401 Unauthorized (no auth)
- 403 Forbidden (no permission)
- 404 Not Found (resource not found)
- 409 Conflict (data conflict)
- 500 Internal Server Error

Пример:
{
  "error": {
    "code": "INVALID_ORDER_AMOUNT",
    "message": "Order amount must be positive",
    "details": {"field": "amount", "value": -500}
  }
}

Шаг 4: Документировать в OpenAPI/Swagger

Пример OpenAPI спецификации:

openapi: 3.0.0
info:
  title: Logistics API
  version: 1.0.0

paths:
  /api/v1/orders:
    post:
      summary: Create new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customer_id, items, delivery_address]
      properties:
        customer_id:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        delivery_address:
          type: string
          minLength: 10

2. API Versioning

Мой подход:

Проблема: API эволюционирует, но нужна backward compatibility

Вариант 1: URL версионирование (я использую)
/api/v1/orders    (версия 1)
/api/v2/orders    (версия 2, breaking changes)

Плюсы:
- Явное разделение
- Легко поддерживать обе версии
- Клиенты явно выбирают версию

Минусы:
- Больше code duplication
- Сложнее с поддержкой

Вариант 2: Header версионирование
GET /api/orders
Headers: API-Version: 2

Плюсы:
- Чистые URLs

Минусы:
- Менее явное
- Сложнее с тестированием

Вариант 3: Content negotiation
GET /api/orders
Accept: application/vnd.api+json;version=2

Плюсы:
- RESTful

Минусы:
- Очень complex
- Редко используется

Мой выбор: Вариант 1 (URL versioning)

Стратегия:
v1 поддерживаю 2 года
v2 поддерживаю 3 года
Потом деприцирую старую версию
Посылаю письма клиентам за 6 месяцев

3. API Security

Мой опыт с authentication:

Тип 1: API Key
- Простой для первых версий
- Заголовок: X-API-Key: abc123def456
- Проблемы: если ключ утечёт, может быть скомпрометирован
- Использую для: internal services, webhooks

Тип 2: OAuth 2.0
- Стандартный для публичных API
- User логинится через UI
- Получает access token
- Использует token в requests
- Проблемы: complexity
- Использую для: public API, third-party интеграции

Тип 3: JWT (JSON Web Token)
- Похоже на OAuth, но simpler
- Token содержит информацию (user_id, role)
- Не требует lookup в БД для каждого запроса
- Используется в моих микросервисах

Тип 4: mTLS (mutual TLS)
- Client и Server взаимно проверяют сертификаты
- Для service-to-service коммуникации
- Использую для: internal API между микросервисами

Пример моей security strategy:

Явная система логистики:

1. External API (для мобильного приложения водителей)
   - OAuth 2.0 с refresh tokens
   - Rate limiting: 1000 req/hour per user
   - HTTPS только
   - CORS для доверенных источников

2. Internal API (между микросервисами)
   - mTLS with service certificates
   - API Key для быстрого development
   - No rate limiting (trusted)

3. Webhook (от платежных систем)
   - API Key в заголовке
   - Signature verification (HMAC-SHA256)
   - HTTPS only
   - IP whitelist

4. Public API (для партнёров)
   - API Key или OAuth
   - Rate limiting: 100 req/hour
   - Перевод на v1 потом на v2 с notice

4. API Documentation

Мой подход к документации:

1. Автоматическая документация (OpenAPI/Swagger)
   - Генерируется из кода
   - Interactive playground
   - Always up-to-date

2. Руководство по использованию (README)
   - Как начать работать
   - Примеры для каждого endpoint
   - Common errors и solutions

3. Architecture documentation
   - Как компоненты взаимодействуют
   - Rate limits и quotas
   - Best practices

Пример структуры в Swagger UI:

GET /api/v1/orders
├─ Summary: "Get list of orders"
├─ Parameters:
│  ├─ status (query, optional)
│  ├─ limit (query, optional, default 20)
│  └─ offset (query, optional, default 0)
├─ Responses:
│  ├─ 200: List of orders
│  ├─ 400: Invalid parameters
│  └─ 401: Unauthorized
└─ Example:
   GET /api/v1/orders?status=pending&limit=10
   Response:
   {
     "data": [{...}, {...}],
     "pagination": {"total": 42, "offset": 0, "limit": 10}
   }

5. API Integration

Пример интеграции с внешним API (платёжная система):

Требования:
- Интегрировать Stripe для обработки платежей
- Обработка webhook'ов при платежах
- Retry logic при failure
- Логирование для аудита

Мой процесс:

1. Analyze Stripe API
   - Endpoints: POST /charges, GET /charges/{id}
   - Webhooks: charge.succeeded, charge.failed
   - Rate limits: 100 req/sec

2. Design своего API
   - POST /api/v1/payments
   - Input: {amount, currency, order_id}
   - Output: {payment_id, status, transaction_id}
   - Async processing (webhook handles updates)

3. Implement integration
   - Stripe SDK для создания платежа
   - Queue для async обработки
   - Retry logic with exponential backoff

4. Test
   - Use Stripe test API key
   - Test cards: 4242 4242 4242 4242 (success)
   - Test cards: 4000 0000 0000 0002 (failure)
   - Webhook testing с Stripe CLI

5. Monitor
   - Логирование всех платежей
   - Alert если failure rate > 5%
   - Daily reconciliation с Stripe

6. Rate Limiting and Throttling

Как я реализую в своих API:

Strategy 1: Token Bucket Algorithm
- Каждый пользователь имеет "ведро" токенов
- За каждый запрос расходуется 1 токен
- Токены пополняются со временем (например, 100 токенов в час)
- Если нет токенов → 429 Too Many Requests

Пример в коде:
GET /api/v1/orders
Headers:
  RateLimit-Limit: 1000
  RateLimit-Remaining: 998
  RateLimit-Reset: 1704067200

Strategy 2: Different limits for different tiers
Free tier: 100 req/hour
Pro tier: 10000 req/hour
Enterprise: unlimited

Strategy 3: Whitelist для critical endpoints
- Payment processing: не лимитировать
- Analytics: лимитировать

7. API Monitoring и Analytics

Что я отслеживаю:

1. Availability
   - Uptime: 99.95%
   - Alert if down
   - Dashboard in Grafana

2. Performance
   - Response time: p50, p95, p99
   - Latency by endpoint
   - Alert if p95 > 200ms

3. Usage
   - Requests per second
   - Popular endpoints
   - Unused endpoints (можно удалить)

4. Errors
   - Error rate по типу
   - 4xx errors (клиент ошибки)
   - 5xx errors (сервер ошибки)
   - Alert if 5xx rate > 1%

5. Security
   - Unusual patterns
   - Failed auth attempts
   - Possible DDoS attacks

Пример monitoring:

8. API Testing

Как я тестирую API:

# Unit test
def test_create_order_valid():
    response = client.post(
        "/api/v1/orders",
        json={"customer_id": "cust-1", "amount": 1000}
    )
    assert response.status_code == 201
    assert response.json()["id"]

# Integration test
@pytest.mark.asyncio
async def test_create_order_with_payment():
    # Create order
    order = await create_order(customer_id="c1", amount=1000)
    
    # Process payment
    payment = await process_payment(order_id=order.id)
    
    # Verify payment status
    assert payment.status == "completed"
    
    # Verify order status updated
    updated_order = await get_order(order.id)
    assert updated_order.status == "confirmed"

# Load test (k6)
import http from 'k6/http';

export let options = {
  vus: 100,  // 100 users
  duration: '30s',
};

export default function() {
  http.get('https://api.example.com/orders');
}

# End-to-end test
async def test_full_order_flow():
    # 1. Login
    # 2. Create order
    # 3. Process payment
    # 4. Verify order in system
    # 5. Check email notification sent

9. API Migration и Deprecation

Пример: миграция с v1 на v2

Фаза 1: Preparation (месяц 1)
- Спроектировать v2
- Реализовать v2 endpoint'ы
- Оба v1 и v2 работают
- Клиенты всё ещё используют v1

Фаза 2: Announcement (месяц 2)
- Объявить deprecation v1
- Письмо всем клиентам
- Документация обновлена
- Deadline: 6 месяцев

Фаза 3: Migration support (месяц 2-7)
- Помочь клиентам мигрировать
- FAQ и examples
- Support для вопросов

Фаза 4: Shutdown (месяц 8)
- v1 returns 410 Gone
- Больше не поддерживаем
- Логирование для очень старых клиентов

Моя политика:
v1: поддержка 2 года
v2: поддержка 3 года
в среднем 1 версия в проде

10. REST vs GraphQL vs gRPC Decision

Как я выбираю:

У меня в системе используются все три:

REST API:
- Public endpoints для мобильного приложения
- Simple CRUD operations
- Хорошая кешируемость

GraphQL:
- Complex queries с вложенностью
- Несколько клиентов с разными потребностями
- Новые проекты

gRPC:
- Internal service-to-service communication
- High-performance requirements
- Streaming данных

Пример архитектуры:

Client App
    ↓ REST
API Gateway
    ↓
├─ OrderService (gRPC)
├─ PaymentService (gRPC)
└─ GraphQL Server (для web)

11. Real-world Challenges и Solutions

Challenge 1: Backward Compatibility

Проблема: Нужен новый field в response, но не хотим сломать клиентов

Решение:
- Добавляю новый field в response
- Старые клиенты игнорируют неизвестный field
- Новые клиенты используют новый field
- No breaking change!

✓ v1 response: {"id": 1, "name": "Order"}
✓ v2 response: {"id": 1, "name": "Order", "created_at": "2025-03-28T..."}

Старый клиент просто не видит created_at, но работает.

Challenge 2: API Abuse / DDoS

Решение:
1. Rate limiting (по IP, по user_id)
2. CAPTCHA для suspicious patterns
3. IP whitelist для internal
4. WAF (Web Application Firewall)
5. Monitoring и alerting

Challenge 3: API Gateway consistency

Есть несколько микросервисов, каждый имеет свой API
Как обеспечить consistency?

Решение:
1. API Gateway (Kong, Nginx)
2. Common authentication
3. Common rate limiting
4. Centralized logging
5. Common error response format

Текущие проекты и API

В PrepBro используется:

API для agent'ов:
GET  /api/v1/agent/answering/next
POST /api/v1/agent/answering/{id}

Внутренняя API:
Multiple microservices communication через gRPC

Документация:
Swagger UI + markdown

Версионирование:
URL-based (v1, v2, etc.)

Auth:
API Keys для агентов
JWT для внутренних сервисов

Выводы

Мой опыт с API:

• 10+ лет дизайна и реализации
• 20+ интеграций с внешними сервисами
• 5+ версий API lifecycle
• 1000+ developers которые использовали мои API
• 99.95% uptime в production

Ключевые learnings:

1. Дизайн API важнее имплементации
2. Документация = часть кода
3. Monitoring с первого дня
4. Версионирование и deprecation важны
5. Security не компромисс
6. Simple > complex (REST > GraphQL когда возможно)