framework-rest-api
Especialista em Arquitetura HTTP, Design de APIs RESTful e Padrões Avançados de Contratos (OpenAPI 3.2, RFC 9110/9112/9113/9114, RFC 10008 e RFC 7807). Cobre semântica completa de verbos (GET, QUERY,
SKILL.mdskills/framework/framework-rest-api/SKILL.md
GitHubDesign de APIs RESTful, Protocolo HTTP e Padrões de Contrato
Esta skill fornece as diretrizes canônicas para arquitetura do Protocolo HTTP (HTTP/1.1, HTTP/2, HTTP/3 sobre QUIC), modelagem de APIs RESTful sob OpenAPI 3.2 e aplicação dos Padrões de Design de APIs (baseado em JJ Geewax e Continuous API Management).
OpenAPI 3.2: Desde a versão 3.2.0 (e 3.2.1), o OpenAPI passou a suportar o método
QUERYnativamente por meio do campo fixoquery(Operation Object) do Path Item Object, definido conforme RFC 10008, além do campo padrãoadditionalOperationspara métodos arbitrários (ex.:LINK). OAS 3.1 não possuía esse campo — ele foi adicionado em 3.2. Portanto, contratos que descrevem o verboQUERYdevem declararopenapi: 3.2.0(ou superior). Ferramentas de geração/validação precisam suportar 3.2 para fidelidade completa aoQUERY.
🌐 1. Semântica dos Verbos e Métodos HTTP (RFC 9110 & RFC 10008)
| Método | Corpo Requisição | Corpo Resposta | Seguro (Safe)? | Idempotente? | Cacheável? | Padrão IETF |
|---|---|---|---|---|---|---|
| GET | Não | Sim | Sim | Sim | Sim | RFC 9110 |
| QUERY | Sim | Sim | Sim | Sim | Sim | RFC 10008 |
| POST | Sim | Sim | Não | Não | Condicional | RFC 9110 |
| PUT | Sim | Sim | Não | Sim | Não | RFC 9110 |
| PATCH | Sim | Sim | Não | Não | Condicional | RFC 5789 / 9110 |
| DELETE | Opcional | Sim | Não | Sim | Não | RFC 9110 |
| HEAD | Não | Não | Sim | Sim | Sim | RFC 9110 |
| OPTIONS | Opcional | Sim | Sim | Sim | Não | RFC 9110 |
Método
QUERY(RFC 10008): Permite consultas e buscas seguras/idempotentes com payload JSON complexo sem violar a semântica doGETe sem efeitos colaterais dePOST. A chave de cache deve incluir URI + hash do corpo da requisição.
QUERYem OpenAPI 3.2: No OAS 3.2.0+ declare a operação no campo fixoquerydo Path Item Object:openapi: 3.2.0 paths: /v1/history: query: summary: Busca complexa de gastos requestBody: content: application/json: schema: { $ref: '#/components/schemas/HistoryQuery' } responses: '200': description: ResultadosPara métodos arbitrários não cobertos pelos campos fixos, use
additionalOperations(chave = método HTTP em caixa-alta, ex.:LINK). Ferramentas/geradores antigos (OAS 3.1) usam fallback para verbos padrão; documente o QUERY em prosa quando o gerador não suportar 3.2.
🎯 2. Modelagem Hierárquica e Métodos Customizados
2.1 Estrutura de URIs
- Coleção:
/v1/orders - Recurso:
/v1/orders/{orderId} - Sub-Recurso:
/v1/orders/{orderId}/items/{itemId} - Métodos Customizados (Custom Actions): Use o sufixo
:para ações não-CRUD:POST /v1/orders/{orderId}:cancelPOST /v1/documents/{documentId}:publishPOST /v1/payments:batchCharge
🔁 3. Padrões Avançados de Operações
3.1 Operações de Longa Duração (Long-Running Operations - LRO)
Para processos assíncronos (> 500ms):
sequenceDiagram
autonumber
actor Client
participant API as API Gateway
participant Worker as Background Worker
participant State as State DB
Client->>API: POST /v1/reports:generate (Filtros)
API->>State: Cria registro da operação (Status: RUNNING)
API-->>Client: 202 Accepted { "name": "operations/rep-998", "done": false }
Worker->>State: Executa e finaliza (Status: SUCCESS, resultUrl)
Client->>API: GET /v1/operations/rep-998
API-->>Client: 200 OK { "done": true, "response": { "downloadUrl": "https://..." } }
3.2 Idempotência em Mutações (Idempotency-Key)
- O cliente envia cabeçalho
Idempotency-Key: <UUIDv4>. - O servidor armazena chave no Redis/DB com TTL (ex: 24h). Se repetida, retorna a resposta original em cache sem reprocessar.
🛠️ 4. Tratamento de Erros Padronizado (RFC 7807 - Problem Details)
Utilize Content-Type: application/problem+json:
{
"type": "https://api.dominio.com/errors/insufficient-funds",
"title": "Saldo insuficiente para transferência",
"status": 422,
"detail": "A conta 1029 possui R$ 50,00 disponíveis, mas a operação exigiu R$ 120,00.",
"instance": "/v1/accounts/1029/transfers/tx-4432",
"invalid_params": [
{
"name": "amount",
"reason": "O montante excede o limite disponível"
}
]
}
🔍 5. Paginação Determinística por Cursor e Rate Limiting
5.1 Paginação por Cursor
GET /v1/events?limit=50&starting_after=evt_98374 HTTP/1.1
{
"data": [...],
"has_more": true,
"next_cursor": "evt_98424"
}
5.2 Cabeçalhos de Rate Limiting (IETF Draft)
RateLimit-Limit: 1000, 1000;window=60RateLimit-Remaining: 980RateLimit-Reset: 15- Resposta para estouro de cota:
429 Too Many Requestscom cabeçalhoRetry-After: 15.
🛡️ 6. Caching HTTP e Cabeçalhos de Segurança
- Validação Condicional:
ETag: "hash321",If-None-Match: "hash321"$\rightarrow$304 Not Modified. - Cache-Control:
public, max-age=3600, stale-while-revalidate=60. - Headers de Segurança Obrigatórios:
Strict-Transport-Security: max-age=63072000; includeSubDomains; preloadContent-Security-Policy: default-src 'self'X-Content-Type-Options: nosniffX-Frame-Options: DENY