Communitygithub.com

Princípios de Design de API

Domine os princípios de design de APIs REST e GraphQL para criar APIs intuitivas, escaláveis e fáceis de manter que encantam os desenvolvedores. Use ao projetar novas APIs, revisar especificações de API ou estabelecer padrões de design de API.

O que é Princípios de Design de API?

Este skill capacita desenvolvedores e arquitetos a projetar APIs REST e GraphQL de alta qualidade seguindo princípios estabelecidos e padrões comprovados. Ele cobre desde os fundamentos de RESTful (arquitetura orientada a recursos, semântica de métodos HTTP) e GraphQL (desenvolvimento schema-first, consultas, mutações e assinaturas) até estratégias de versionamento de API. O skill fornece exemplos de código práticos em Python (FastAPI e Ariadne) para padrões como design de coleções de recursos, paginação e filtragem, tratamento de erros com códigos de status HTTP, HATEOAS e prevenção do problema N+1 em GraphQL usando DataLoaders. Adequado para uso em plataformas como Claude Code, Cursor ou Codex, ele é ideal ao projetar novas APIs, refatorar existentes, estabelecer padrões de equipe ou revisar especificações antes da implementação, ajudando a evitar armadilhas comuns como over-fetching, mudanças abruptas e documentação insuficiente.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/api/api-design-principles-algusaem-algusaem-portfolio

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Princípios de Design de API faz?

Domine os princípios de design de APIs REST e GraphQL para criar APIs intuitivas, escaláveis e fáceis de manter que encantam os desenvolvedores e resistem ao teste do tempo.

Quando Usar Este Skill

  • Projetar novas APIs REST ou GraphQL
  • Refatorar APIs existentes para melhor usabilidade
  • Estabelecer padrões de design de API para sua equipe
  • Revisar especificações de API antes da implementação
  • Migrar entre paradigmas de API (REST para GraphQL, etc.)
  • Criar documentação de API amigável para desenvolvedores
  • Otimizar APIs para casos de uso específicos (mobile, integrações de terceiros)

Conceitos Principais

1. Princípios de Design RESTful

Arquitetura Orientada a Recursos

  • Recursos são substantivos (usuários, pedidos, produtos), não verbos
  • Use métodos HTTP para ações (GET, POST, PUT, PATCH, DELETE)
  • URLs representam hierarquias de recursos
  • Convenções de nomenclatura consistentes

Semântica dos Métodos HTTP:

  • GET: Recuperar recursos (idempotente, seguro)
  • POST: Criar novos recursos
  • PUT: Substituir recurso inteiro (idempotente)
  • PATCH: Atualizações parciais de recursos
  • DELETE: Remover recursos (idempotente)

2. Princípios de Design GraphQL

Desenvolvimento Schema-First

  • Tipos definem seu modelo de domínio
  • Queries para leitura de dados
  • Mutações para modificação de dados
  • Assinaturas para atualizações em tempo real

Estrutura de Query:

  • Clientes solicitam exatamente o que precisam
  • Único endpoint, múltiplas operações
  • Schema fortemente tipado
  • Introspecção embutida

3. Estratégias de Versionamento de API

Versionamento por URL:

/api/v1/usuarios
/api/v2/usuarios

Versionamento por Cabeçalho:

Accept: application/vnd.api+json; version=1

Versionamento por Parâmetro de Query:

/api/usuarios?version=1

Padrões de Design de API REST

Padrão 1: Design de Coleção de Recursos

# Bom: Endpoints orientados a recursos
GET    /api/usuarios              # Listar usuários (com paginação)
POST   /api/usuarios              # Criar usuário
GET    /api/usuarios/{id}         # Obter usuário específico
PUT    /api/usuarios/{id}         # Substituir usuário
PATCH  /api/usuarios/{id}         # Atualizar campos do usuário
DELETE /api/usuarios/{id}         # Excluir usuário

# Recursos aninhados
GET    /api/usuarios/{id}/pedidos  # Obter pedidos do usuário
POST   /api/usuarios/{id}/pedidos  # Criar pedido para o usuário

# Ruim: Endpoints orientados a ação (evitar)
POST   /api/criarUsuario
POST   /api/obterUsuarioPorId
POST   /api/excluirUsuario

Padrão 2: Paginação e Filtragem

from typing import List, Optional
from pydantic import BaseModel, Field

class ParametrosPaginacao(BaseModel):
    pagina: int = Field(1, ge=1, description="Número da página")
    tamanho_pagina: int = Field(20, ge=1, le=100, description="Itens por página")

class ParametrosFiltro(BaseModel):
    status: Optional[str] = None
    criado_apos: Optional[str] = None
    busca: Optional[str] = None

class RespostaPaginada(BaseModel):
    itens: List[dict]
    total: int
    pagina: int
    tamanho_pagina: int
    paginas: int

    @property
    def tem_proximo(self) -> bool:
        return self.pagina < self.paginas

    @property
    def tem_anterior(self) -> bool:
        return self.pagina > 1

# Exemplo de endpoint FastAPI
from fastapi import FastAPI, Query, Depends

app = FastAPI()

@app.get("/api/usuarios", response_model=RespostaPaginada)
async def listar_usuarios(
    pagina: int = Query(1, ge=1),
    tamanho_pagina: int = Query(20, ge=1, le=100),
    status: Optional[str] = Query(None),
    busca: Optional[str] = Query(None)
):
    # Aplicar filtros
    consulta = construir_consulta(status=status, busca=busca)

    # Contar total
    total = await contar_usuarios(consulta)

    # Buscar página
    deslocamento = (pagina - 1) * tamanho_pagina
    usuarios = await buscar_usuarios(consulta, limite=tamanho_pagina, deslocamento=deslocamento)

    return RespostaPaginada(
        itens=usuarios,
        total=total,
        pagina=pagina,
        tamanho_pagina=tamanho_pagina,
        paginas=(total + tamanho_pagina - 1) // tamanho_pagina
    )

Padrão 3: Tratamento de Erros e Códigos de Status

from fastapi import HTTPException, status
from pydantic import BaseModel
from typing import Any

class RespostaErro(BaseModel):
    erro: str
    mensagem: str
    detalhes: Optional[dict] = None
    timestamp: str
    caminho: str

class DetalheErroValidacao(BaseModel):
    campo: str
    mensagem: str
    valor: Any

# Respostas de erro consistentes
CODIGOS_STATUS = {
    "sucesso": 200,
    "criado": 201,
    "sem_conteudo": 204,
    "requisicao_invalida": 400,
    "nao_autorizado": 401,
    "proibido": 403,
    "nao_encontrado": 404,
    "conflito": 409,
    "nao_processavel": 422,
    "erro_interno": 500
}

def levantar_nao_encontrado(recurso: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "erro": "NaoEncontrado",
            "mensagem": f"{recurso} não encontrado",
            "detalhes": {"id": id}
        }
    )

def levantar_erro_validacao(erros: List[DetalheErroValidacao]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "erro": "ErroValidacao",
            "mensagem": "Falha na validação da requisição",
            "detalhes": {"erros": [e.dict() for e in erros]}
        }
    )

# Exemplo de uso
@app.get("/api/usuarios/{usuario_id}")
async def obter_usuario(usuario_id: str):
    usuario = await buscar_usuario(usuario_id)
    if not usuario:
        levantar_nao_encontrado("Usuário", usuario_id)
    return usuario

Padrão 4: HATEOAS (Hypermedia as the Engine of Application State)

class RespostaUsuario(BaseModel):
    id: str
    nome: str
    email: str
    _links: dict

    @classmethod
    def de_usuario(cls, usuario: Usuario, url_base: str):
        return cls(
            id=usuario.id,
            nome=usuario.nome,
            email=usuario.email,
            _links={
                "self": {"href": f"{url_base}/api/usuarios/{usuario.id}"},
                "pedidos": {"href": f"{url_base}/api/usuarios/{usuario.id}/pedidos"},
                "atualizar": {
                    "href": f"{url_base}/api/usuarios/{usuario.id}",
                    "method": "PATCH"
                },
                "excluir": {
                    "href": f"{url_base}/api/usuarios/{usuario.id}",
                    "method": "DELETE"
                }
            }
        )

Padrões de Design GraphQL

Padrão 1: Design de Schema

# schema.graphql

# Definições de tipo claras
type Usuario {
  id: ID!
  email: String!
  nome: String!
  criadoEm: DateTime!

  # Relacionamentos
  pedidos(primeiro: Int = 20, depois: String, status: StatusPedido): ConexaoPedido!

  perfil: PerfilUsuario
}

type Pedido {
  id: ID!
  status: StatusPedido!
  total: Dinheiro!
  itens: [ItemPedido!]!
  criadoEm: DateTime!

  # Referência inversa
  usuario: Usuario!
}

# Padrão de paginação (estilo Relay)
type ConexaoPedido {
  arestas: [ArestaPedido!]!
  infoPagina: InfoPagina!
  totalContagem: Int!
}

type ArestaPedido {
  no: Pedido!
  cursor: String!
}

type InfoPagina {
  temProximaPagina: Boolean!
  temPaginaAnterior: Boolean!
  cursorInicio: String
  cursorFim: String
}

# Enums para segurança de tipos
enum StatusPedido {
  PENDENTE
  CONFIRMADO
  ENVIADO
  ENTREGUE
  CANCELADO
}

# Scalars customizados
scalar DateTime
scalar Dinheiro

# Raiz de Query
type Query {
  usuario(id: ID!): Usuario
  usuarios(primeiro: Int = 20, depois: String, busca: String): ConexaoUsuario!

  pedido(id: ID!): Pedido
}

# Raiz de Mutation
type Mutation {
  criarUsuario(input: CriarUsuarioInput!): CriarUsuarioPayload!
  atualizarUsuario(input: AtualizarUsuarioInput!): AtualizarUsuarioPayload!
  excluirUsuario(id: ID!): ExcluirUsuarioPayload!

  criarPedido(input: CriarPedidoInput!): CriarPedidoPayload!
}

# Tipos de input para mutações
input CriarUsuarioInput {
  email: String!
  nome: String!
  senha: String!
}

# Tipos de payload para mutações
type CriarUsuarioPayload {
  usuario: Usuario
  erros: [Erro!]
}

type Erro {
  campo: String
  mensagem: String!
}

Padrão 2: Design de Resolvers

from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass

query = QueryType()
mutation = MutationType()
tipo_usuario = ObjectType("Usuario")

@query.field("usuario")
async def resolver_usuario(obj, info, id: str) -> Optional[dict]:
    """Resolve um único usuário por ID."""
    return await buscar_usuario_por_id(id)

@query.field("usuarios")
async def resolver_usuarios(
    obj,
    info,
    primeiro: int = 20,
    depois: Optional[str] = None,
    busca: Optional[str] = None
) -> dict:
    """Resolve lista paginada de usuários."""
    # Decodificar cursor
    deslocamento = decodificar_cursor(depois) if depois else 0

    # Buscar usuários
    usuarios = await buscar_usuarios(
        limite=primeiro + 1,  # Buscar um extra para verificar temProximaPagina
        deslocamento=deslocamento,
        busca=busca
    )

    # Paginação
    tem_proximo = len(usuarios) > primeiro
    if tem_proximo:
        usuarios = usuarios[:primeiro]

    arestas = [
        {
            "no": usuario,
            "cursor": codificar_cursor(deslocamento + i)
        }
        for i, usuario in enumerate(usuarios)
    ]

    return {
        "arestas": arestas,
        "infoPagina": {
            "temProximaPagina": tem_proximo,
            "temPaginaAnterior": deslocamento > 0,
            "cursorInicio": arestas[0]["cursor"] if arestas else None,
            "cursorFim": arestas[-1]["cursor"] if arestas else None
        },
        "totalContagem": await contar_usuarios(busca=busca)
    }

@tipo_usuario.field("pedidos")
async def resolver_pedidos_usuario(usuario: dict, info, primeiro: int = 20) -> dict:
    """Resolve pedidos do usuário (prevenção N+1 com DataLoader)."""
    # Usar DataLoader para agrupar requisições
    carregador = info.context["carregadores"]["pedidos_por_usuario"]
    pedidos = await carregador.load(usuario["id"])

    return paginar_pedidos(pedidos, primeiro)

@mutation.field("criarUsuario")
async def resolver_criar_usuario(obj, info, input: dict) -> dict:
    """Cria novo usuário."""
    try:
        # Validar input
        validar_input_usuario(input)

        # Criar usuário
        usuario = await criar_usuario(
            email=input["email"],
            nome=input["nome"],
            senha=hash_senha(input["senha"])
        )

        return {
            "usuario": usuario,
            "erros": []
        }
    except ErroValidacao as e:
        return {
            "usuario": None,
            "erros": [{"campo": e.campo, "mensagem": e.mensagem}]
        }

Padrão 3: DataLoader (Prevenção do Problema N+1)

from aiodataloader import DataLoader
from typing import List, Optional

class CarregadorUsuario(DataLoader):
    """Carrega usuários em lote por ID."""

    async def batch_load_fn(self, ids_usuario: List[str]) -> List[Optional[dict]]:
        """Carrega múltiplos usuários em uma única consulta."""
        usuarios = await buscar_usuarios_por_ids(ids_usuario)

        # Mapear resultados de volta à ordem do input
        mapa_usuarios = {usuario["id"]: usuario for usuario in usuarios}
        return [mapa_usuarios.get(id_usuario) for id_usuario in ids_usuario]

class CarregadorPedidosPorUsuario(DataLoader):
    """Carrega pedidos em lote por ID do usuário."""

    async def batch_load_fn(self, ids_usuario: List[str]) -> List[List[dict]]:
        """Carrega pedidos para múltiplos usuários em uma única consulta."""
        pedidos = await buscar_pedidos_por_ids_usuario(ids_usuario)

        # Agrupar pedidos por usuario_id
        pedidos_por_usuario = {}
        for pedido in pedidos:
            usuario_id = pedido["usuario_id"]
            if usuario_id not in pedidos_por_usuario:
                pedidos_por_usuario[usuario_id] = []
            pedidos_por_usuario[usuario_id].append(pedido)

        # Retornar na ordem do input
        return [pedidos_por_usuario.get(id_usuario, []) for id_usuario in ids_usuario]

# Configuração do contexto
def criar_contexto():
    return {
        "carregadores": {
            "usuario": CarregadorUsuario(),
            "pedidos_por_usuario": CarregadorPedidosPorUsuario()
        }
    }

Melhores Práticas

APIs REST

  1. Nomenclatura Consistente: Use substantivos no plural para coleções (/usuarios, não /usuario)
  2. Sem Estado (Stateless): Cada requisição contém todas as informações necessárias
  3. Use Códigos de Status HTTP Corretamente: 2xx sucesso, 4xx erros do cliente, 5xx erros do servidor
  4. Versionar Sua API: Planeje mudanças disruptivas desde o primeiro dia
  5. Paginação: Sempre pagine grandes coleções
  6. Limitação de Taxa (Rate Limiting): Proteja sua API com limites de requisição
  7. Documentação: Use OpenAPI/Swagger para documentação interativa

APIs GraphQL

  1. Schema Primeiro: Projete o schema antes de escrever resolvers
  2. Evite N+1: Use DataLoaders para busca eficiente de dados
  3. Validação de Input: Valide nos níveis de schema e resolver
  4. Tratamento de Erros: Retorne erros estruturados nos payloads de mutação
  5. Paginação: Use paginação baseada em cursor (especificação Relay)
  6. Depreciação: Use a diretiva @deprecated para migração gradual
  7. Monitoramento: Acompanhe a complexidade das consultas e o tempo de execução

Armadilhas Comuns

  • Over-fetching/Under-fetching (REST): Resolvido no GraphQL, mas requer DataLoaders
  • Mudanças Disruptivas: Versione APIs ou use estratégias de depreciação
  • Formatos de Erro Inconsistentes: Padronize as respostas de erro
  • Limitação de Taxa Ausente: APIs sem limites são vulneráveis a abusos
  • Documentação Pobre: APIs não documentadas frustram desenvolvedores
  • Ignorar Semântica HTTP: POST para operações idempotentes quebra expectativas
  • Acoplamento Forte: Estrutura da API não deve espelhar o schema do banco de dados

Recursos

  • referencias/melhores-praticas-rest.md: Guia abrangente de design de API REST
  • referencias/design-schema-graphql.md: Padrões e antipadrões de schema GraphQL
  • referencias/estrategias-versionamento-api.md: Abordagens de versionamento e caminhos de migração
  • assets/modelo-api-rest.py: Modelo de API REST com FastAPI
  • assets/modelo-schema-graphql.graphql: Exemplo completo de schema GraphQL
  • assets/lista-verificacao-design-api.md: Lista de verificação de revisão pré-implementação
  • scripts/gerador-openapi.py: Gere especificações OpenAPI a partir do código

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Habilidades Relacionadas