# Api Design Principles > Domina los principios de diseño REST y GraphQL para construir APIs intuitivas, escalables y mantenibles que encanten a los desarrolladores. Fuente: https://skillsagentes.com/skills/wshobson/agents/api-design-principles Markdown: https://skillsagentes.com/skills/wshobson/agents/api-design-principles.md Repositorio: https://github.com/wshobson/agents Autor: wshobson Licencia: MIT Actualizado: hace 4 meses Coste de contexto: 55 tok instalada, 901 tok al activarse, 9.8k tok con todos los archivos del bundle Bundle: 6 archivos, 38 KB Permisos que pide: ninguno declarado ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add wshobson/agents --skill api-design-principles --agent claude-code # Cursor npx -y skills add wshobson/agents --skill api-design-principles --agent cursor # Codex npx -y skills add wshobson/agents --skill api-design-principles --agent codex # Gemini CLI npx -y skills add wshobson/agents --skill api-design-principles --agent gemini # Windsurf npx -y skills add wshobson/agents --skill api-design-principles --agent windsurf # Cline npx -y skills add wshobson/agents --skill api-design-principles --agent cline ``` ## Qué hace - Aplica principios de diseño REST y GraphQL para construir APIs intuitivas, escalables y mantenibles - Define convenciones de nombres, semántica HTTP y estrategias de versionado - Cubre buenas prácticas como paginación, rate limiting, manejo de errores y documentación OpenAPI ## Cuándo usarla - Diseñar nuevas APIs REST o GraphQL - Refactorizar APIs existentes para mejorar su usabilidad - Establecer estándares de diseño de API para un equipo - Revisar especificaciones de API antes de implementarlas ## Qué la activa - "Ayúdame a diseñar una API REST para gestionar pedidos" - "Revisa esta especificación GraphQL antes de implementarla" - "¿Cómo debería versionar mi API pública?" - "Necesito establecer estándares de diseño de API para mi equipo" ## Antes de instalar - Incluye un archivo references/details.md con patrones y ejemplos detallados para consultar cuando haga falta. ## Archivos - SKILL.md — 4 KB - assets/api-design-checklist.md — 4 KB - assets/rest-api-template.py — 5 KB - references/details.md — 10 KB - references/graphql-schema-design.md — 9 KB - references/rest-best-practices.md — 7 KB ## SKILL.md Reproducido tal cual desde wshobson/agents bajo MIT. Esta sección es el documento original y está en inglés. # API Design Principles Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time. ## When to Use This Skill - Designing new REST or GraphQL APIs - Refactoring existing APIs for better usability - Establishing API design standards for your team - Reviewing API specifications before implementation - Migrating between API paradigms (REST to GraphQL, etc.) - Creating developer-friendly API documentation - Optimizing APIs for specific use cases (mobile, third-party integrations) ## Core Concepts ### 1. RESTful Design Principles **Resource-Oriented Architecture** - Resources are nouns (users, orders, products), not verbs - Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE) - URLs represent resource hierarchies - Consistent naming conventions **HTTP Methods Semantics:** - `GET`: Retrieve resources (idempotent, safe) - `POST`: Create new resources - `PUT`: Replace entire resource (idempotent) - `PATCH`: Partial resource updates - `DELETE`: Remove resources (idempotent) ### 2. GraphQL Design Principles **Schema-First Development** - Types define your domain model - Queries for reading data - Mutations for modifying data - Subscriptions for real-time updates **Query Structure:** - Clients request exactly what they need - Single endpoint, multiple operations - Strongly typed schema - Introspection built-in ### 3. API Versioning Strategies **URL Versioning:** ``` /api/v1/users /api/v2/users ``` **Header Versioning:** ``` Accept: application/vnd.api+json; version=1 ``` **Query Parameter Versioning:** ``` /api/users?version=1 ``` ## Detailed patterns and worked examples Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient. ## Best Practices ### REST APIs 1. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`) 2. **Stateless**: Each request contains all necessary information 3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors 4. **Version Your API**: Plan for breaking changes from day one 5. **Pagination**: Always paginate large collections 6. **Rate Limiting**: Protect your API with rate limits 7. **Documentation**: Use OpenAPI/Swagger for interactive docs ### GraphQL APIs 1. **Schema First**: Design schema before writing resolvers 2. **Avoid N+1**: Use DataLoaders for efficient data fetching 3. **Input Validation**: Validate at schema and resolver levels 4. **Error Handling**: Return structured errors in mutation payloads 5. **Pagination**: Use cursor-based pagination (Relay spec) 6. **Deprecation**: Use `@deprecated` directive for gradual migration 7. **Monitoring**: Track query complexity and execution time ## Common Pitfalls - **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders - **Breaking Changes**: Version APIs or use deprecation strategies - **Inconsistent Error Formats**: Standardize error responses - **Missing Rate Limits**: APIs without limits are vulnerable to abuse - **Poor Documentation**: Undocumented APIs frustrate developers - **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations - **Tight Coupling**: API structure shouldn't mirror database schema ## Dónde encaja - Categoría: [Desarrollo de APIs](https://skillsagentes.com/categorias/desarrollo-apis.md) — Diseña, prueba y documenta APIs HTTP y GraphQL. - Creador: [wshobson](https://skillsagentes.com/creators/wshobson.md) — 183 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Hermes Tweet](https://skillsagentes.com/skills/wshobson/agents/hermes-tweet.md): Instala y opera Hermes Tweet, un plugin de Hermes Agent para investigar X/Twitter, leer timelines, analizar tweets y ejecutar operaciones privadas o de cambio de estado con aprobación previa. - [Superself](https://skillsagentes.com/skills/wshobson/agents/superself.md): Úsalo cuando un proyecto guarda su estado en Superself: lee `self context` al iniciar sesión, vincula el trabajo a una work unit, reporta con evidencia y registra decisiones confirmadas. - [Grounded Vault](https://skillsagentes.com/skills/wshobson/agents/grounded-vault.md): Úsalo para mantener un almacén Markdown de conocimiento donde cada afirmación compilada se rastrea hasta una fuente inmutable y el drift se detecta con git diff sin gastar tokens. - [Postgresql Table Design](https://skillsagentes.com/skills/wshobson/agents/postgresql-table-design.md): Úsalo al diseñar o revisar un esquema específico de PostgreSQL: buenas prácticas, tipos de datos, indexación, restricciones, patrones de rendimiento y funciones avanzadas. - [Prompt Engineering Patterns](https://skillsagentes.com/skills/wshobson/agents/prompt-engineering-patterns.md): Úsalo cuando pidan optimizar un prompt, mejorar su rendimiento, diseñar una plantilla, aplicar chain-of-thought, few-shot prompting o técnicas avanzadas de prompt engineering para producción. ## Skills relacionadas - [Rag Implementation](https://skillsagentes.com/skills/wshobson/agents/rag-implementation.md): Construye sistemas RAG (Retrieval-Augmented Generation) para aplicaciones LLM con bases de datos vectoriales y búsqueda semántica, integrando conocimiento externo. - [Paypal Integration](https://skillsagentes.com/skills/wshobson/agents/paypal-integration.md): Integra el procesamiento de pagos de PayPal, con soporte para express checkout, suscripciones y gestión de reembolsos en flujos de comercio electrónico. - [Openapi Spec Generation](https://skillsagentes.com/skills/wshobson/agents/openapi-spec-generation.md): Genera y mantiene especificaciones OpenAPI 3.1 a partir de código, con enfoque design-first y patrones de validación de contratos de API. - [Nodejs Backend Patterns](https://skillsagentes.com/skills/wshobson/agents/nodejs-backend-patterns.md): Construye servicios backend de Node.js listos para producción con Express/Fastify, cubriendo middleware, manejo de errores, autenticación, bases de datos y diseño de APIs. - [Defi Protocol Templates](https://skillsagentes.com/skills/wshobson/agents/defi-protocol-templates.md): Implementa protocolos DeFi con plantillas listas para producción de staking, AMMs, gobernanza y flash loans. Úsalo al construir aplicaciones de finanzas descentralizadas o contratos inteligentes. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)