Design da API

🎯 Princípios de Design

A API do Payment Gateway segue princípios RESTful com foco em simplicidade, consistência e escalabilidade.

1. RESTful Design

• Recursos bem definidos: Cada endpoint representa um recurso específico

• Métodos HTTP semânticos: GET (leitura), POST (criação), PUT (atualização), DELETE (remoção)

• Status codes apropriados: 200, 201, 400, 401, 403, 404, 500

• URLs hierárquicas: /api/v1/payments/{id}/refunds

2. Versionamento

/api/v1/payments
/api/v2/payments  # Nova versão mantém compatibilidade

3. Formato de Resposta Padrão

{
  "success": true,
  "data": { /* payload */ },
  "meta": {
    "timestamp": "2024-12-12T10:30:00Z",
    "version": "v1",
    "request_id": "req_123456"
  }
}

🔧 Padrões Implementados

Paginação

{
  "data": [ /* items */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Filtros e Ordenação

GET /api/v1/payments?status=succeeded&sort=-created_at&limit=50

Idempotência

• Chave de idempotência no header: Idempotency-Key

• Operações POST/PUT são idempotentes

• Cache de 24h para respostas idempotentes

📊 Rate Limiting

• 1000 requests/hour por IP (geral)

• 100 requests/hour para endpoints de pagamento

• Headers de rate limit nas respostas

---

Documentação atualizada: December 2024