Noções Básicas de Design de API

9 exemplos para design de API HTTP em serviços Rust - 6 básicos e 3 intermediários.

Pré-requisitos

[dependencies]
axum = "0.8"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

• Os padrões aqui se aplicam a gateways HTTP Axum, Actix e tonic.
• Emparelhe com DTOs serde na fronteira HTTP.

Exemplos Básicos

1. URLs de Recursos

Substantivos em caminhos, verbos em métodos HTTP.

GET    /users
POST   /users
GET    /users/{id}
PATCH  /users/{id}
DELETE /users/{id}

• Nomes de recursos no plural.
• Evite estilo RPC como /createUser para CRUD.
• Aninhe sub-recursos: /users/{id}/orders.

Relacionado: GraphQL em Rust - modelo de consulta alternativo

2. Códigos de Status

Mapeie resultados para semânticas HTTP.

201 Created     - Sucesso POST com recurso
204 No Content  - Sucesso DELETE
409 Conflict    - campo único duplicado
422 Unprocessable Entity - falha de validação

• Não retorne 200 para erros.
• 401 não autenticado vs 403 proibido.
• 429 quando o limite de taxa é atingido.

3. Envelope de Erro

Erros estáveis e legíveis por máquina.

{"error":{"code":"invalid_email","message":"Formato de email inválido","field":"email"}}

• Inclua code, message, field opcional.
• Registre o ID de correlação apenas no lado do servidor.
• Nunca exponha rastros de pilha (stack traces).

Relacionado: Validação de Entrada e Injeção - erros de validação

4. Versionamento

Versões explícitas da API.

/v1/users
Accept: application/vnd.example.v1+json

• Prefixo de URL é o mais simples para APIs públicas.
• Documente cronogramas de descontinuação.
• Evite alterações que quebrem a compatibilidade sem aviso.

5. Paginação

Listagem baseada em cursor.

GET /items?limit=20&cursor=eyJpZCI6MTB9

• Prefira cursores em vez de OFFSET em tabelas grandes.
• Retorne next_cursor no corpo da resposta.
• Limite o limit máximo.

6. Idempotência

Retentativas seguras para POST.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

• Armazene a chave + hash da resposta no Redis ou SQL.
• Retorne a mesma resposta em caso de chave duplicada dentro do TTL.
• Necessário para operações de pagamento e criação.

Relacionado: Retentativas, Timeouts e Backoff - retentativas do cliente

Exemplos Intermediários

7. Negociação de Conteúdo

JSON como padrão com tipo de conteúdo explícito.

// handlers retornam Json<T> - Axum define application/json

• Suporte ao cabeçalho Accept se for multiformato.
• Documente o charset UTF-8 para JSON.

8. Detalhes do Problema (padrão opcional)

RFC 7807 application/problem+json para erros.

{"type":"https://api.example.com/errors/validation","title":"Falha na validação","status":422}

• Campos padrão: type, title, status, detail.
• Alinhe com geradores de SDK do cliente.

9. Metadados OpenAPI

Descreva a API para os consumidores.

// use utoipa::ToSchema em DTOs e utoipa::path em handlers

• Mantenha o OpenAPI gerado a partir do código sempre que possível.
• Publique em /docs apenas em ambientes não produtivos ou atrás de autenticação.

Relacionado: Melhores Práticas de APIs e Segurança - linha de base completa

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.