api-design

Estrelas6

Forks1

Atualizado19 de abril de 2026 às 03:46

Design de API REST seguindo boas práticas. Use quando pedirem para projetar API, definir endpoints, criar contrato REST ou OpenAPI.

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

wesleyosantos91

wesleyosantos91/multi-agents

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Desenvolvedores de softwareInformática e Matemática·SOC 15-1252

SKILL.md

readonly

name	api-design
description	Design de API REST seguindo boas práticas. Use quando pedirem para projetar API, definir endpoints, criar contrato REST ou OpenAPI.
argument-hint	[contexto adicional]

API Design — REST Best Practices

Projete ou revise uma API REST seguindo boas práticas consolidadas.

Princípios

URLs

Substantivos no plural: /orders, /users, /payments
Hierarquia para relações: /users/{id}/orders
Sem verbos na URL (use HTTP methods): POST /orders não POST /createOrder
Kebab-case para multi-word: /order-items
Máximo 3 níveis de aninhamento

HTTP Methods

Method	Semântica	Idempotente	Body
GET	Ler recurso(s)	Sim	Não
POST	Criar recurso	Não	Sim
PUT	Substituir recurso inteiro	Sim	Sim
PATCH	Atualizar parcialmente	Não*	Sim
DELETE	Remover recurso	Sim	Não

Status Codes

Código	Quando usar
200	Sucesso com body
201	Recurso criado (POST) — incluir `Location` header
204	Sucesso sem body (DELETE, PUT)
400	Input inválido — detalhar o que está errado
401	Não autenticado
403	Autenticado mas sem permissão
404	Recurso não encontrado
409	Conflito (duplicata, estado inválido)
422	Validação de negócio falhou
429	Rate limit excedido
500	Erro interno — nunca expor stack trace

Paginação

GET /orders?page=1&size=20&sort=createdAt,desc

{
  "content": [...],
  "page": { "number": 1, "size": 20, "totalElements": 150, "totalPages": 8 }
}

Erros (RFC 9457 — Problem Details)

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Account balance is 30.00 but transfer requires 50.00",
  "instance": "/transfers/txn-123"
}

Filtros

Query parameters para filtros simples: ?status=PENDING&minAmount=100
Operadores quando necessário: ?createdAfter=2024-01-01
Não inventar DSL de query complexa — se precisar, considere GraphQL

Versionamento

Preferir evolução backward-compatible (adicionar campos, nunca remover)
Se inevitável: URL path (/v2/orders) ou header (Accept-Version: 2)

Output

Quando projetando API, entregue:

Tabela de endpoints (method, URL, descrição, auth)
Request/response examples para cada endpoint
Códigos de erro esperados
Notas sobre paginação, filtros, ordenação

Mais deste repositório

mesmo repositório

adr

wesleyosantos91/multi-agents

Acione o `tech-writer` para criar um novo Architecture Decision Record (ADR).

2026-04-196

adr-template

wesleyosantos91/multi-agents

Template e guia para ADRs (Architecture Decision Records): quando criar, estrutura, exemplos. Use quando documentar decisões arquiteturais ou criar ADRs.

2026-04-196

android-patterns

wesleyosantos91/multi-agents

Padrões Android modernos: Kotlin, Jetpack Compose, MVVM, Hilt, Room, Navigation, Coroutines, testes. Use quando implementar features em Android nativo.

2026-04-196

angular-patterns

wesleyosantos91/multi-agents

Padrões Angular modernos: Standalone Components, Signals, inject(), HttpClient, RxJS, Testing. Use quando implementar features em Angular ou configurar projeto Angular.

2026-04-196

angularjs-migration

wesleyosantos91/multi-agents

Migração AngularJS para Angular: estratégia incremental, ngUpgrade, dual-boot, padrões de coexistência. Use quando planejar ou executar migração de AngularJS (1.x) para Angular moderno.

2026-04-196

arch-review

wesleyosantos91/multi-agents

Acione o `architect-reviewer` para uma análise arquitetural focada.

2026-04-196

name	api-design
description	Design de API REST seguindo boas práticas. Use quando pedirem para projetar API, definir endpoints, criar contrato REST ou OpenAPI.
argument-hint	[contexto adicional]

API Design — REST Best Practices

Projete ou revise uma API REST seguindo boas práticas consolidadas.

Princípios

URLs

Substantivos no plural: /orders, /users, /payments
Hierarquia para relações: /users/{id}/orders
Sem verbos na URL (use HTTP methods): POST /orders não POST /createOrder
Kebab-case para multi-word: /order-items
Máximo 3 níveis de aninhamento

HTTP Methods

Method	Semântica	Idempotente	Body
GET	Ler recurso(s)	Sim	Não
POST	Criar recurso	Não	Sim
PUT	Substituir recurso inteiro	Sim	Sim
PATCH	Atualizar parcialmente	Não*	Sim
DELETE	Remover recurso	Sim	Não

Status Codes

Código	Quando usar
200	Sucesso com body
201	Recurso criado (POST) — incluir `Location` header
204	Sucesso sem body (DELETE, PUT)
400	Input inválido — detalhar o que está errado
401	Não autenticado
403	Autenticado mas sem permissão
404	Recurso não encontrado
409	Conflito (duplicata, estado inválido)
422	Validação de negócio falhou
429	Rate limit excedido
500	Erro interno — nunca expor stack trace

Paginação

GET /orders?page=1&size=20&sort=createdAt,desc

{
  "content": [...],
  "page": { "number": 1, "size": 20, "totalElements": 150, "totalPages": 8 }
}

Erros (RFC 9457 — Problem Details)

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Account balance is 30.00 but transfer requires 50.00",
  "instance": "/transfers/txn-123"
}

Filtros

Query parameters para filtros simples: ?status=PENDING&minAmount=100
Operadores quando necessário: ?createdAfter=2024-01-01
Não inventar DSL de query complexa — se precisar, considere GraphQL

Versionamento

Preferir evolução backward-compatible (adicionar campos, nunca remover)
Se inevitável: URL path (/v2/orders) ou header (Accept-Version: 2)

Output

Quando projetando API, entregue:

Tabela de endpoints (method, URL, descrição, auth)
Request/response examples para cada endpoint
Códigos de erro esperados
Notas sobre paginação, filtros, ordenação