Communitygithub.com

majiayu000/claude-skill-registry

Domina los principios de diseño de APIs REST y GraphQL para construir APIs intuitivas, escalables y mantenibles que encanten a los desarrolladores. Úsalo al diseñar nuevas APIs, revisar especificaciones de APIs o establecer estándares de diseño de APIs.

¿Qué es claude-skill-registry?

Esta habilidad proporciona una guía integral y práctica para diseñar APIs de alto nivel, cubriendo tanto REST como GraphQL. Está diseñada para ayudar a desarrolladores y equipos de ingeniería a crear APIs que sean intuitivas, escalables y mantenibles, siguiendo las mejores prácticas de la industria. La habilidad es útil en varias etapas del ciclo de vida de una API: desde el diseño inicial, pasando por la refactorización y el establecimiento de estándares de equipo, hasta la revisión de especificaciones y la migración entre paradigmas. Se basa en plataformas y herramientas estándar como FastAPI para REST, Ariadne para GraphQL y DataLoaders para optimización de rendimiento. El contenido de SKILL.md está estructurado con principios básicos, patrones de diseño detallados con código de ejemplo, y mejores prácticas, cubriendo temas como versionado, paginación, manejo de errores, HATEOAS, diseño de esquemas y resolución de problemas comunes como el problema N+1 en GraphQL.

Compatible con✓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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Principios de Diseño de APIs

Domina los principios de diseño de APIs REST y GraphQL para construir APIs intuitivas, escalables y mantenibles que encanten a los desarrolladores y resistan el paso del tiempo.

Cuándo usar esta habilidad

  • Diseñar nuevas APIs REST o GraphQL
  • Refactorizar APIs existentes para mejorar la usabilidad
  • Establecer estándares de diseño de APIs para tu equipo
  • Revisar especificaciones de APIs antes de la implementación
  • Migrar entre paradigmas de API (REST a GraphQL, etc.)
  • Crear documentación de API amigable para desarrolladores
  • Optimizar APIs para casos de uso específicos (móvil, integraciones de terceros)

Conceptos básicos

1. Principios de diseño RESTful

Arquitectura orientada a recursos

  • Los recursos son sustantivos (usuarios, pedidos, productos), no verbos
  • Utiliza métodos HTTP para las acciones (GET, POST, PUT, PATCH, DELETE)
  • Las URLs representan jerarquías de recursos
  • Convenciones de nomenclatura consistentes

Semántica de métodos HTTP:

  • GET: Recuperar recursos (idempotente, seguro)
  • POST: Crear nuevos recursos
  • PUT: Reemplazar el recurso completo (idempotente)
  • PATCH: Actualizaciones parciales de recursos
  • DELETE: Eliminar recursos (idempotente)

2. Principios de diseño de GraphQL

Desarrollo basado en esquemas

  • Los tipos definen tu modelo de dominio
  • Consultas para leer datos
  • Mutaciones para modificar datos
  • Suscripciones para actualizaciones en tiempo real

Estructura de consultas:

  • Los clientes solicitan exactamente lo que necesitan
  • Un único endpoint, múltiples operaciones
  • Esquema fuertemente tipado
  • Introspección incorporada

3. Estrategias de versionado de APIs

Versionado en URL:

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

Versionado en cabecera:

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

Versionado por parámetro de consulta:

/api/users?version=1

Patrones de diseño de APIs REST

Patrón 1: Diseño de colecciones de recursos

# Bueno: Endpoints orientados a recursos
GET    /api/users              # Listar usuarios (con paginación)
POST   /api/users              # Crear usuario
GET    /api/users/{id}         # Obtener usuario específico
PUT    /api/users/{id}         # Reemplazar usuario
PATCH  /api/users/{id}         # Actualizar campos del usuario
DELETE /api/users/{id}         # Eliminar usuario

# Recursos anidados
GET    /api/users/{id}/orders  # Obtener pedidos del usuario
POST   /api/users/{id}/orders  # Crear pedido para el usuario

# Malo: Endpoints orientados a acciones (evitar)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

Patrón 2: Paginación y filtrado

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

class PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="Número de página")
    page_size: int = Field(20, ge=1, le=100, description="Elementos 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

# Ejemplo de endpoint en 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)

    # Obtener 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
    )

Patrón 3: Manejo de errores y códigos de estado

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

# Respuestas de error 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} no encontrado",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "La validación de la solicitud falló",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# Ejemplo 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("User", user_id)
    return user

Patrón 4: HATEOAS (Hypermedia as the Engine of Application State)

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"
                }
            }
        )

Patrones de diseño de GraphQL

Patrón 1: Diseño de esquemas

# schema.graphql

# Definiciones de tipos claras
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

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

  profile: UserProfile
}

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

  # Referencia inversa
  user: User!
}

# Patrón de paginación (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 seguridad de tipos
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

# Escalares personalizados
scalar DateTime
scalar Money

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

  order(id: ID!): Order
}

# Raíz de mutación
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!

  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

# Tipos de entrada para mutaciones
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

# Tipos de carga para mutaciones
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: String!
}

Patrón 2: Diseño de resolutores

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]:
    """Resuelve un usuario 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:
    """Resuelve una lista paginada de usuarios."""
    # Decodificar cursor
    offset = decode_cursor(after) if after else 0

    # Obtener usuarios
    users = await fetch_users(
        limit=first + 1,  # Obtener uno extra para comprobar hasNextPage
        offset=offset,
        search=search
    )

    # Paginación
    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:
    """Resuelve los pedidos de un usuario (prevención N+1 con DataLoader)."""
    # Usar DataLoader para agrupar solicitudes
    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:
    """Crea un nuevo usuario."""
    try:
        # Validar entrada
        validate_user_input(input)

        # Crear usuario
        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}]
        }

Patrón 3: DataLoader (Prevención del problema N+1)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """Carga por lotes usuarios por ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """Carga múltiples usuarios en una sola consulta."""
        users = await fetch_users_by_ids(user_ids)

        # Mapear resultados al orden 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):
    """Carga por lotes pedidos por ID de usuario."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """Carga pedidos para múltiples usuarios en una sola 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)

        # Devolver en el orden de entrada
        return [orders_by_user.get(user_id, []) for user_id in user_ids]

# Configuración del contexto
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

Mejores prácticas

APIs REST

  1. Nomenclatura consistente: Usa sustantivos en plural para colecciones (/users, no /user)
  2. Sin estado: Cada solicitud contiene toda la información necesaria
  3. Usa códigos de estado HTTP correctamente: 2xx éxito, 4xx errores de cliente, 5xx errores de servidor
  4. Versiona tu API: Planifica cambios incompatibles desde el primer día
  5. Paginación: Siempre pagina colecciones grandes
  6. Límite de tasa: Protege tu API con límites de tasa
  7. Documentación: Usa OpenAPI/Swagger para documentación interactiva

APIs GraphQL

  1. Esquema primero: Diseña el esquema antes de escribir resolutores
  2. Evita N+1: Usa DataLoaders para la obtención eficiente de datos
  3. Validación de entrada: Valida a nivel de esquema y de resolutor
  4. Manejo de errores: Devuelve errores estructurados en las cargas de mutación
  5. Paginación: Usa paginación basada en cursores (especificación Relay)
  6. Obsolescencia: Usa la directiva @deprecated para migración gradual
  7. Monitoreo: Rastrea la complejidad de las consultas y el tiempo de ejecución

Errores comunes

  • Sobrecarga/Subcarga (REST): Se soluciona en GraphQL pero requiere DataLoaders
  • Cambios incompatibles: Versiona las APIs o usa estrategias de obsolescencia
  • Formatos de error inconsistentes: Estandariza las respuestas de error
  • Límites de tasa faltantes: Las APIs sin límites son vulnerables al abuso
  • Documentación deficiente: Las APIs sin documentación frustran a los desarrolladores
  • Ignorar la semántica HTTP: POST para operaciones idempotentes rompe las expectativas
  • Acoplamiento fuerte: La estructura de la API no debe reflejar el esquema de la base de datos

Recursos

  • references/rest-best-practices.md: Guía completa de diseño de APIs REST
  • references/graphql-schema-design.md: Patrones y anti-patrones de esquemas GraphQL
  • references/api-versioning-strategies.md: Enfoques de versionado y rutas de migración
  • assets/rest-api-template.py: Plantilla de API REST con FastAPI
  • assets/graphql-schema-template.graphql: Ejemplo completo de esquema GraphQL
  • assets/api-design-checklist.md: Lista de verificación previa a la implementación
  • scripts/openapi-generator.py: Genera especificaciones OpenAPI a partir del 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.

Skills relacionados