Agent skill

api-design

API Design - Princípios RESTful e boas práticas

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/api-design-criptogus-liquid-ai

SKILL.md

API Design - Princípios RESTful

Esta skill implementa boas práticas para design de APIs RESTful consistentes e intuitivas.

Princípios Fundamentais

┌─────────────────────────────────────────────────────────────┐
│  1. CONSISTÊNCIA - Padrões previsíveis em toda API         │
│  2. SIMPLICIDADE - Fácil de entender e usar                │
│  3. DOCUMENTAÇÃO - Auto-explicativa quando possível        │
│  4. VERSIONAMENTO - Evoluir sem quebrar clientes           │
└─────────────────────────────────────────────────────────────┘

URL Structure

Naming Convention

# ✅ BOM - Substantivos no plural, kebab-case
GET /api/v1/users
GET /api/v1/user-profiles
GET /api/v1/order-items

# ❌ RUIM - Verbos, singular, camelCase
GET /api/v1/getUser
GET /api/v1/user
GET /api/v1/orderItems

Hierarquia de Recursos

# Recurso principal
GET /api/v1/users

# Sub-recurso (pertence a user)
GET /api/v1/users/{userId}/orders

# Máximo 2-3 níveis de aninhamento
GET /api/v1/users/{userId}/orders/{orderId}/items

# Se muito profundo, promova a recurso próprio
GET /api/v1/order-items?orderId={orderId}

HTTP Methods

Method Uso Idempotente Body
GET Ler recurso(s) Sim Não
POST Criar recurso Não Sim
PUT Substituir recurso completo Sim Sim
PATCH Atualizar parcialmente Sim* Sim
DELETE Remover recurso Sim Não

Exemplos CRUD

bash
# Listar todos os usuários
GET /api/v1/users

# Obter usuário específico
GET /api/v1/users/123

# Criar usuário
POST /api/v1/users
Body: { "name": "João", "email": "[email protected]" }

# Atualizar usuário (completo)
PUT /api/v1/users/123
Body: { "name": "João Silva", "email": "[email protected]", "phone": "..." }

# Atualizar usuário (parcial)
PATCH /api/v1/users/123
Body: { "name": "João Silva" }

# Remover usuário
DELETE /api/v1/users/123

Status Codes

Sucesso (2xx)

Code Quando Usar
200 OK GET/PUT/PATCH bem-sucedido
201 Created POST criou recurso
204 No Content DELETE bem-sucedido

Erro do Cliente (4xx)

Code Quando Usar
400 Bad Request Dados inválidos
401 Unauthorized Não autenticado
403 Forbidden Autenticado mas sem permissão
404 Not Found Recurso não existe
409 Conflict Conflito (ex: email duplicado)
422 Unprocessable Entity Validação falhou
429 Too Many Requests Rate limit excedido

Erro do Servidor (5xx)

Code Quando Usar
500 Internal Server Error Erro inesperado
502 Bad Gateway Serviço upstream falhou
503 Service Unavailable Serviço temporariamente indisponível

Request/Response Format

Request Headers

http
Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json
Accept-Language: pt-BR
X-Request-ID: uuid-for-tracing

Response Structure (Sucesso)

json
{
  "data": {
    "id": "123",
    "name": "João",
    "email": "[email protected]",
    "createdAt": "2025-01-13T10:30:00Z"
  }
}

Response Structure (Lista)

json
{
  "data": [
    { "id": "1", "name": "João" },
    { "id": "2", "name": "Maria" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "perPage": 20,
    "totalPages": 5
  }
}

Response Structure (Erro)

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": [
      {
        "field": "email",
        "message": "Email inválido"
      }
    ]
  }
}

Paginação

Query Parameters

bash
# Offset-based (simples)
GET /api/v1/users?page=2&perPage=20

# Cursor-based (melhor performance)
GET /api/v1/users?cursor=abc123&limit=20

Response com Paginação

json
{
  "data": [...],
  "meta": {
    "total": 1000,
    "page": 2,
    "perPage": 20
  },
  "links": {
    "self": "/api/v1/users?page=2",
    "first": "/api/v1/users?page=1",
    "prev": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=3",
    "last": "/api/v1/users?page=50"
  }
}

Filtering, Sorting, Search

Filtros

bash
# Filtro simples
GET /api/v1/users?status=active

# Múltiplos valores
GET /api/v1/users?status=active,pending

# Operadores
GET /api/v1/orders?total[gte]=100&total[lte]=500
GET /api/v1/users?createdAt[after]=2025-01-01

Ordenação

bash
# Ascendente
GET /api/v1/users?sort=name

# Descendente
GET /api/v1/users?sort=-createdAt

# Múltiplos campos
GET /api/v1/users?sort=-createdAt,name

Busca

bash
# Busca simples
GET /api/v1/users?search=joão

# Busca em campo específico
GET /api/v1/users?name[contains]=silva

Versionamento

Estratégias

Estratégia Exemplo Pros Cons
URL Path /api/v1/users Explícito, cacheável URL muda
Header Accept-Version: 1 URL limpa Menos visível
Query ?version=1 Fácil testar Pode ser esquecido

Recomendação: URL Path para APIs públicas

Evolução

# Versão atual
GET /api/v1/users

# Nova versão (breaking changes)
GET /api/v2/users

# Manter v1 funcionando por período de deprecação

Autenticação

Bearer Token (JWT)

http
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

http
X-API-Key: your-api-key-here

OAuth 2.0 Flows

Flow Uso
Authorization Code Web apps com backend
PKCE Mobile/SPA apps
Client Credentials Server-to-server

Rate Limiting

Headers de Resposta

http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1673568000
Retry-After: 60

Resposta 429

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido",
    "retryAfter": 60
  }
}

HATEOAS (Links)

json
{
  "data": {
    "id": "123",
    "name": "João",
    "status": "active"
  },
  "links": {
    "self": "/api/v1/users/123",
    "orders": "/api/v1/users/123/orders",
    "deactivate": "/api/v1/users/123/deactivate"
  }
}

Ações Não-CRUD

Opção 1: Verbo como Sub-recurso

bash
# Ações em recurso
POST /api/v1/users/123/activate
POST /api/v1/orders/456/cancel
POST /api/v1/emails/789/send

Opção 2: Campo de Status

bash
PATCH /api/v1/users/123
Body: { "status": "active" }

Checklist de Design

Antes de Implementar

  • Recursos identificados como substantivos?
  • Hierarquia de recursos definida?
  • Versionamento planejado?
  • Autenticação definida?

Durante Implementação

  • Status codes corretos?
  • Validação de input?
  • Error handling consistente?
  • Rate limiting configurado?

Antes de Publicar

  • Documentação atualizada?
  • Exemplos funcionando?
  • Testes de integração?
  • Monitoring configurado?

Anti-Patterns

Anti-Pattern Problema Solução
Verbos na URL /getUsers, /createUser Use HTTP methods
Inconsistência /users vs /User Padronize plural/kebab
Expor IDs internos IDs sequenciais Use UUIDs ou slugs
Retornar HTML em API Dificulta consumo Sempre JSON
Ignorar erros Retornar 200 com erro Status codes corretos

Esta skill ativa AUTOMATICAMENTE quando:

  • Design de novos endpoints
  • Discussão sobre estrutura de API
  • Problemas com REST/HTTP

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results