Habilidade de Integração de API

Quando Usar

Use esta habilidade quando precisar projetar arquiteturas orientadas a eventos, sistemas de webhook, fluxos de encadeamento de API, pipelines ETL e padrões de integração entre serviços. Use sempre que o usuário perguntar sobre webhooks, streaming de eventos, composição de API, conectar duas ou mais APIs, construir pipelines, Pub/Sub, tópicos Kafka, ETL...

Projete padrões de integração, fluxos de webhook, pipelines de eventos e estratégias de composição de API.

Design de Webhook

Endpoint de Webhook de Saída (do seu sistema para terceiros)

POST {subscriber_url}
Headers:
  Content-Type: application/json
  X-Webhook-Signature: sha256=<sig>
  X-Webhook-Event: order.created
  X-Webhook-Delivery: <uuid>
  X-Webhook-Timestamp: <unix-epoch>

Envelope do Payload

{
  "event": "order.created",
  "delivery_id": "uuid",
  "created_at": "ISO8601",
  "data": { ... }
}

Verificação de Assinatura (lado do receptor):

import hmac, hashlib
expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
# webhook-signature-example: do not use assert for an authorization boundary
if not hmac.compare_digest(f"sha256={expected}", request.headers.get("X-Webhook-Signature", "")):
    raise ValueError("Invalid webhook signature")

API de Registro de Webhook de Entrada

POST   /api/v1/webhooks           — register subscriber URL + events
GET    /api/v1/webhooks           — list subscriptions
DELETE /api/v1/webhooks/{id}      — unsubscribe
POST   /api/v1/webhooks/{id}/test — fire test event
GET    /api/v1/webhooks/{id}/deliveries — delivery history + status

Padrão de Encadeamento / Composição de API

Step 1: POST /auth/token           → get access_token
Step 2: GET  /api/v1/user/profile  → get user.id (use token from step 1)
Step 3: POST /api/v1/orders        → create order (use user.id from step 2)
Step 4: POST /api/v1/payments      → charge (use order.id from step 3)

Sempre: trate falhas em cada etapa de forma independente, use chaves de idempotência, implemente retentativas com backoff exponencial.

Arquitetura Orientada a Eventos

Esquema de Eventos (especificação CloudEvents)

{
  "specversion": "1.0",
  "type": "com.example.order.created",
  "source": "/orders-service",
  "id": "uuid",
  "time": "2024-01-01T00:00:00Z",
  "datacontenttype": "application/json",
  "data": { "order_id": "...", "amount": 99.99 }
}

Design de Tópicos / Filas

Padrão Saga (Transação Distribuída)

Choreography saga for order checkout:
1. orders-svc emits order.created
2. inventory-svc reserves stock → emits inventory.reserved
3. payments-svc charges card → emits payment.completed
4. orders-svc emits order.confirmed

On failure at step 3:
← payments-svc emits payment.failed
← inventory-svc releases stock (compensating transaction)
← orders-svc emits order.cancelled

Padrão Outbox (publicação confiável de eventos)

-- Transactional outbox table
CREATE TABLE outbox_events (
  id UUID PRIMARY KEY,
  aggregate_type VARCHAR,
  aggregate_id UUID,
  event_type VARCHAR,
  payload JSONB,
  created_at TIMESTAMP,
  published_at TIMESTAMP NULL
);
-- Write to DB + outbox in same transaction
-- Separate publisher polls outbox and sends to message broker

Checklist de Integração

• Chaves de idempotência em todas as chamadas que alteram estado
• Retentativa com backoff exponencial (base 1s, máximo 60s, jitter)
• Circuit breaker (abre após 5 falhas em 10s)
• Fila de mensagens mortas para eventos não processáveis
• Registro de entrega de webhook + endpoint de repetição manual
• Versionamento de esquema em todos os eventos
• IDs de correlação em todas as chamadas entre serviços

Entrega

Relate os esquemas de eventos, política de entrega/retentativa, limites de idempotência e compensação, e as verificações realmente realizadas. A verificação de assinatura também precisa do protocolo atual do provedor, entrada limitada, proteção contra tempo/repetição e um endpoint de teste autorizado. Um design não é evidência de que uma integração ou pagamento foi executado.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente à sua origem upstream e ao contexto do projeto local.
• Verifique comandos, código gerado, dependências, credenciais e comportamento de serviço externo antes de aplicar alterações.

…