Communitygithub.com

majiayu000/claude-skill-registry

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

O que é claude-skill-registry?

Esta skill capacita agentes de IA, como o Claude Code, a projetar e revisar APIs REST e GraphQL seguindo princípios sólidos de design. Ela cobre desde conceitos fundamentais, como arquitetura orientada a recursos e esquemas primeiro, até padrões avançados como paginação, tratamento de erros, HATEOAS e resolvers GraphQL, incluindo prevenção do problema N+1 com DataLoaders. A skill inclui exemplos práticos de código em Python (FastAPI) e GraphQL, e está disponível em repositórios como claude-code, cursor e codex. Útil para quem precisa estabelecer padrões de design, revisar especificações ou criar documentação de API amigável para desenvolvedores.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/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

Princípios de Design de API

Domine os princípios de design de APIs REST e GraphQL para construir APIs intuitivas, escaláveis e de fácil manutenção que encantam desenvolvedores e resistem ao teste do tempo.

Quando Usar Esta Skill

  • Projetando novas APIs REST ou GraphQL
  • Refatorando APIs existentes para melhor usabilidade
  • Estabelecendo padrões de design de API para sua equipe
  • Revisando especificações de API antes da implementação
  • Migrando entre paradigmas de API (REST para GraphQL, etc.)
  • Criando documentação de API amigável para desenvolvedores
  • Otimizando 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 recurso
  • DELETE: Remover recursos (idempotente)

2. Princípios de Design GraphQL

Desenvolvimento Esquema-Primeiro

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

Estrutura de Consulta:

  • Clientes solicitam exatamente o que precisam
  • Ponto de extremidade único, múltiplas operações
  • Esquema fortemente tipado
  • Introspecção integrada

3. Estratégias de Versionamento de API

Versionamento por URL:

/api/v1/users
/api/v2/users

Versionamento por Cabeçalho:

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

Versionamento por Parâmetro de Consulta:

/api/users?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/users              # Listar usuários (com paginação)
POST   /api/users              # Criar usuário
GET    /api/users/{id}         # Obter usuário específico
PUT    /api/users/{id}         # Substituir usuário
PATCH  /api/users/{id}         # Atualizar campos do usuário
DELETE /api/users/{id}         # Excluir usuário

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

# Ruim: Endpoints orientados a ação (evitar)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

Padrão 2: Paginação e Filtragem

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

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

class FilterParams(BaseModel):
    status: Optional[str] = None
    created_after: Optional[str] = None
    search: Optional[str] = None

class PaginatedResponse(BaseModel):
    items: List[dict]
    total: int
    page: int
    page_size: int
    pages: int

    @property
    def has_next(self) -> bool:
        return self.page < self.pages

    @property
    def has_prev(self) -> bool:
        return self.page > 1

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

app = FastAPI()

@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    status: Optional[str] = Query(None),
    search: Optional[str] = Query(None)
):
    # Aplicar filtros
    query = build_query(status=status, search=search)

    # Contar total
    total = await count_users(query)

    # Buscar página
    offset = (page - 1) * page_size
    users = await fetch_users(query, limit=page_size, offset=offset)

    return PaginatedResponse(
        items=users,
        total=total,
        page=page,
        page_size=page_size,
        pages=(total + page_size - 1) // page_size
    )

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

from fastapi import HTTPException, status
from pydantic import BaseModel

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[dict] = None
    timestamp: str
    path: str

class ValidationErrorDetail(BaseModel):
    field: str
    message: str
    value: Any

# Respostas de erro consistentes
STATUS_CODES = {
    "success": 200,
    "created": 201,
    "no_content": 204,
    "bad_request": 400,
    "unauthorized": 401,
    "forbidden": 403,
    "not_found": 404,
    "conflict": 409,
    "unprocessable": 422,
    "internal_error": 500
}

def raise_not_found(resource: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NotFound",
            "message": f"{resource} não encontrado",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "Falha na validação da requisição",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# Exemplo de uso
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
    user = await fetch_user(user_id)
    if not user:
        raise_not_found("Usuário", user_id)
    return user

Padrão 4: HATEOAS (Hipermídia como Motor do Estado da Aplicação)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    _links: dict

    @classmethod
    def from_user(cls, user: User, base_url: str):
        return cls(
            id=user.id,
            name=user.name,
            email=user.email,
            _links={
                "self": {"href": f"{base_url}/api/users/{user.id}"},
                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
                "update": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "PATCH"
                },
                "delete": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "DELETE"
                }
            }
        )

Padrões de Design GraphQL

Padrão 1: Design de Esquema

# schema.graphql

# Definições de tipo claras
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

  # Relacionamentos
  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!

  profile: UserProfile
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Money!
  items: [OrderItem!]!
  createdAt: DateTime!

  # Referência reversa
  user: User!
}

# Padrão de paginação (estilo Relay)
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Enums para segurança de tipo
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

# Scalars personalizados
scalar DateTime
scalar Money

# Raiz de consulta
type Query {
  user(id: ID!): User
  users(first: Int = 20, after: String, search: String): UserConnection!

  order(id: ID!): Order
}

# Raiz de mutação
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!

  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

# Tipos de entrada para mutações
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

# Tipos de payload para mutações
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: 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()
user_type = ObjectType("User")

@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
    """Resolver usuário único por ID."""
    return await fetch_user_by_id(id)

@query.field("users")
async def resolve_users(
    obj,
    info,
    first: int = 20,
    after: Optional[str] = None,
    search: Optional[str] = None
) -> dict:
    """Resolver lista paginada de usuários."""
    # Decodificar cursor
    offset = decode_cursor(after) if after else 0

    # Buscar usuários
    users = await fetch_users(
        limit=first + 1,  # Buscar um extra para verificar hasNextPage
        offset=offset,
        search=search
    )

    # Paginação
    has_next = len(users) > first
    if has_next:
        users = users[:first]

    edges = [
        {
            "node": user,
            "cursor": encode_cursor(offset + i)
        }
        for i, user in enumerate(users)
    ]

    return {
        "edges": edges,
        "pageInfo": {
            "hasNextPage": has_next,
            "hasPreviousPage": offset > 0,
            "startCursor": edges[0]["cursor"] if edges else None,
            "endCursor": edges[-1]["cursor"] if edges else None
        },
        "totalCount": await count_users(search=search)
    }

@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
    """Resolver pedidos do usuário (prevenção N+1 com DataLoader)."""
    # Usar DataLoader para agrupar requisições
    loader = info.context["loaders"]["orders_by_user"]
    orders = await loader.load(user["id"])

    return paginate_orders(orders, first)

@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
    """Criar novo usuário."""
    try:
        # Validar entrada
        validate_user_input(input)

        # Criar usuário
        user = await create_user(
            email=input["email"],
            name=input["name"],
            password=hash_password(input["password"])
        )

        return {
            "user": user,
            "errors": []
        }
    except ValidationError as e:
        return {
            "user": None,
            "errors": [{"field": e.field, "message": e.message}]
        }

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

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """Carregar usuários em lote por ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """Carregar múltiplos usuários em uma única consulta."""
        users = await fetch_users_by_ids(user_ids)

        # Mapear resultados de volta para a ordem de entrada
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """Carregar pedidos em lote por ID de usuário."""

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

        # Agrupar pedidos por user_id
        orders_by_user = {}
        for order in orders:
            user_id = order["user_id"]
            if user_id not in orders_by_user:
                orders_by_user[user_id] = []
            orders_by_user[user_id].append(order)

        # Retornar na ordem de entrada
        return [orders_by_user.get(user_id, []) for user_id in user_ids]

# Configuração de contexto
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

Melhores Práticas

APIs REST

  1. Nomenclatura Consistente: Use plurais para coleções (/users, não /user)
  2. 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. Versione Sua API: Planeje mudanças disruptivas desde o primeiro dia
  5. Paginação: Sempre pagine grandes coleções
  6. Rate Limiting: Proteja sua API com limites de taxa
  7. Documentação: Use OpenAPI/Swagger para documentação interativa

APIs GraphQL

  1. Esquema Primeiro: Projete o esquema antes de escrever resolvers
  2. Evite N+1: Use DataLoaders para busca eficiente de dados
  3. Validação de Entrada: Valide nos níveis de esquema 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 complexidade de consulta e tempo de execução

Armadilhas Comuns

  • Sobrecarga/Subcarga (REST): Corrigido no GraphQL, mas requer DataLoaders
  • Mudanças Disruptivas: Versione APIs ou use estratégias de depreciação
  • Formatos de Erro Inconsistentes: Padronize respostas de erro
  • Falta de Limites de Taxa: APIs sem limites são vulneráveis a abuso
  • Documentação Pobre: APIs não documentadas frustram desenvolvedores
  • Ignorar Semântica HTTP: POST para operações idempotentes quebra expectativas
  • Acoplamento Forte: A estrutura da API não deve espelhar o esquema do banco de dados

Recursos

  • references/rest-best-practices.md: Guia abrangente de design de API REST
  • references/graphql-schema-design.md: Padrões e antipadrões de esquema GraphQL
  • references/api-versioning-strategies.md: Abordagens de versionamento e caminhos de migração
  • assets/rest-api-template.py: Template de API REST FastAPI
  • assets/graphql-schema-template.graphql: Exemplo completo de esquema GraphQL
  • assets/api-design-checklist.md: Lista de verificação de pré-implementação
  • scripts/openapi-generator.py: Gerar 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

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

Habilidades Relacionadas