Idempotência

Operações de escrita (POST, PUT, PATCH, DELETE) podem falhar por problemas de rede antes de você receber a resposta. Retentar a mesma operação pode criar efeitos colaterais indesejados (ex: criar um estudante duplicado).

A API suporta idempotência via header Idempotency-Key para evitar duplicação.

Como funciona

1. Envie o header Idempotency-Key com um identificador único (string até 255 caracteres) em requisições de escrita.
2. A API processa a requisição normalmente e armazena a resposta (status + body) no cache por 24 horas, vinculada à sua API key e à chave de idempotência.
3. Se a mesma combinação apiKey + Idempotency-Key for usada novamente dentro de 24h, a API retorna a mesma resposta da primeira requisição, sem re-executar a operação.

sequenceDiagram
    participant C as Cliente
    participant A as API GDREdu

    C->>A: POST /v1/students (Idempotency-Key: abc-123)
    A-->>A: Processa normalmente
    A->>A: Armazena resposta por 24h
    A-->>C: 201 Created

    C->>A: POST /v1/students (Idempotency-Key: abc-123) [retry]
    A-->>A: Cache hit (mesma key)
    A-->>C: 201 Created (mesma resposta, sem re-executar)

Uso

curl -X POST https://api.gdredu.com/v1/students \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name": "João Silva", "registration": "2026001"}'

Regras

:::note
Erros 5xx não são cacheados.
Se a primeira requisição retornar 500 INTERNAL_ERROR, a idempotência não é aplicada — você pode retentar livremente. Apenas respostas 2xx e 4xx são cacheadas.
:::

Gerando uma chave de idempotência

Qualquer string única serve. Recomendamos UUID v4 para garantir unicidade global:

import { randomUUID } from 'crypto'
const idempotencyKey = randomUUID()

import uuid
idempotency_key = str(uuid.uuid4())

$idempotencyKey = uniqid('', true);

Quando usar

Sem o header

Se você não enviar Idempotency-Key, a API processa cada requisição normalmente, sem cache. Você é responsável por lidar com duplicação em caso de retentativas.