api-design-principles

Descripción general de la skill api-design-principles

Qué te ayuda a hacer api-design-principles

La skill api-design-principles sirve como apoyo para revisar y redactar diseños de APIs REST y GraphQL. Resulta especialmente útil cuando necesitas convertir un requisito de producto todavía impreciso en una API mejor estructurada, revisar una especificación existente antes de implementarla o estandarizar cómo un equipo diseña endpoints y esquemas.

Para qué usuarios y equipos encaja mejor

Usa api-design-principles si estás:

• diseñando una API nueva, pública o interna
• revisando propuestas de endpoints o esquemas para comprobar su consistencia
• eligiendo entre patrones REST y GraphQL
• intentando detectar errores de diseño evitables antes de escribir código
• creando estándares ligeros de diseño de APIs para un equipo

Es especialmente útil para ingenieros backend, tech leads, equipos de plataforma y agentes de IA a los que se les pide proponer contratos de API en lugar de implementaciones completas.

Qué hace que merezca la pena instalar esta skill

Su valor principal no está en la novedad, sino en la estructura. La skill reúne orientación práctica de diseño, una checklist de revisión, ejemplos REST y patrones de esquemas GraphQL en un flujo reutilizable e invocable por prompt. Frente a un prompt genérico del tipo “diseña una API”, api-design-principles le da a tu agente mejores criterios por defecto en aspectos como:

• nombres de recursos y estructura de URLs
• semántica de métodos HTTP y códigos de estado
• paginación, filtrado y versionado
• consistencia en la forma de los errores
• organización de esquemas GraphQL, nulabilidad y modelado de inputs

Lo que no hace

Esto no es un API gateway, ni un generador de código, ni un framework completo de gobierno de APIs. Mejorará la calidad del diseño y la cobertura de revisión, pero seguirás necesitando tus propias reglas para auth, restricciones del dominio, compliance y operación en runtime. Si necesitas una base de implementación, la plantilla FastAPI incluida ayuda solo para REST; la skill destaca más en principios de diseño que en entrega end-to-end.

Cómo usar la skill api-design-principles

Instalar la skill api-design-principles

Instala la skill desde el repositorio wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill api-design-principles

Si tu entorno de agente permite descubrir skills automáticamente, invoca api-design-principles cuando la tarea trate de la forma de la API, la revisión del contrato o la elección de paradigma, y no de implementar la lógica de negocio.

Lee primero estos archivos

Para adoptarla más rápido, lee los archivos en este orden:

1. SKILL.md para entender el alcance y el flujo integrado
2. assets/api-design-checklist.md para los criterios de revisión
3. references/rest-best-practices.md para convenciones REST concretas
4. references/graphql-schema-design.md para patrones de esquemas
5. assets/rest-api-template.py si además quieres un ejemplo de implementación REST

Este orden importa porque la checklist es el artefacto de mayor valor práctico para trabajo real de revisión, mientras que las referencias aportan ejemplos que tu agente puede reutilizar en sus respuestas.

Conoce los datos clave que necesita la skill

La api-design-principles skill funciona mejor cuando le das:

• objetos del dominio: users, orders, invoices, projects
• acciones principales del usuario: create, list, update, search, approve
• tipo de cliente: public third-party, internal web app, mobile, partner integration
• restricciones sobre el estilo de API: REST, GraphQL o “help me choose”
• necesidades operativas: pagination, filtering, versioning, rate limits, webhooks, real-time
• restricciones de compatibilidad: existing endpoints, legacy payloads, migration limits

Sin esta información, el agente suele producir endpoints genéricos o un esquema superficial que parece limpio, pero no refleja tus patrones reales de uso.

Convierte una petición vaga en un prompt sólido

Petición débil:

• “Design an API for tasks.”

Petición mejor:

• “Use api-design-principles to design a REST API for a task management product. Main resources: workspaces, projects, tasks, comments. Clients: web app and mobile app. Required features: pagination, filtering by status and assignee, partial updates, audit-friendly timestamps, stable error responses, and versioning. Avoid deep nesting. Return endpoint list, request and response examples, status codes, and design rationale.”

Por qué esta versión es mejor:

• nombra los recursos
• aporta contexto sobre los clientes
• deja claros los comportamientos imprescindibles
• añade restricciones que la skill puede optimizar

Usa api-design-principles para revisiones de diseño REST

Para trabajo con REST, pídele a la skill que evalúe:

• sustantivos de recursos frente a verbos de acción
• nesting superficial frente a nesting excesivamente profundo
• corrección en el uso de GET, POST, PUT, PATCH, DELETE
• elección de códigos de estado
• diseño de query parameters para filtering, sorting y search
• patrón de paginación elegido
• estrategia de versioning y deprecation
• consistencia de las respuestas de error

Un prompt práctico:

• “Run api-design-principles against this draft endpoint list and flag naming, method semantics, pagination, and error-handling issues. Rewrite only the parts that violate established conventions.”

Así mantienes la salida centrada en la revisión, en lugar de disparar un rediseño completo.

Usa api-design-principles para diseño de esquemas GraphQL

En GraphQL, la skill resulta más útil cuando le pides decisiones sobre la estructura del esquema, no solo listas de tipos. Buenas peticiones incluyen:

• organización modular del esquema
• decisiones de nulabilidad
• tipos de input y payload
• nombres de queries y mutations
• uso de interfaces y unions
• paginación tipo connection
• diseño de campos para consultas habituales de clientes

Un prompt sólido:

• “Use api-design-principles to design a GraphQL schema for a B2B support platform. Include User, Ticket, and Comment types, cursor pagination, clear mutation inputs, and sensible nullability. Explain tradeoffs where fields should remain nullable.”

Decide entre REST y GraphQL con la skill

Si aún no lo tienes claro, pídele una recomendación comparativa ligada a tu producto:

• diversidad de peticiones entre clientes
• necesidad de seleccionar datos parciales
• facilidad para caching y uso de CDN
• curva de aprendizaje de tu equipo
• audiencia interna frente a desarrolladores externos

Un prompt útil:

• “Apply api-design-principles for API Development to compare REST and GraphQL for an internal analytics platform used by web dashboards and automation scripts. Recommend one approach and include the operational tradeoffs.”

Usa la checklist como puerta de control antes de implementar

El archivo assets/api-design-checklist.md es el mejor recurso para equipos que quieren revisiones consistentes. Trátalo como una puerta de control previa al desarrollo:

• revisa cada recurso y operación
• verifica la paginación en todas las colecciones
• elige explícitamente un enfoque de versioning
• confirma el comportamiento de errores y códigos de estado
• detecta patrones que falten para search, sort o sparse fields

Aquí es donde la skill aporta valor real para la toma de decisiones: te ayuda a detectar defectos del contrato antes de que la implementación los deje fijados.

Reutiliza la plantilla REST con cuidado

assets/rest-api-template.py es una referencia útil, pero no conviene confundirla con una base universal lista para producción. Demuestra patrones como:

• estructura en FastAPI
• paginación y validación
• uso de enum
• ubicación del middleware
• manejo consistente de respuestas

También incluye TODOs evidentes para producción, como una configuración permisiva de CORS y de trusted hosts. Úsala para ver cómo las decisiones de diseño se traducen a código, no como un punto de partida seguro para copiar y pegar.

Flujo habitual para obtener mejores resultados

Un flujo de api-design-principles usage que suele funcionar bien es:

1. describir objetivos del producto y actores
2. listar recursos y operaciones de mayor valor
3. elegir REST, GraphQL o pedir a la skill que compare
4. solicitar un primer contrato
5. hacer una pasada de revisión usando las categorías de la checklist
6. refinar sobre casos límite: pagination, errors, versioning, nullability
7. solo entonces pasar a la implementación

Esta secuencia reduce retrabajo porque estabiliza antes los nombres y la semántica del contrato.

Preguntas frecuentes sobre la skill api-design-principles

¿api-design-principles es buena para principiantes?

Sí, siempre que ya entiendas conceptos básicos de HTTP o GraphQL. La skill es legible y está orientada a ejemplos, pero da por hecho que estás tomando decisiones de diseño, no aprendiendo desarrollo backend desde cero. Los principiantes le sacarán más partido si la usan para revisar borradores que para inventar una API completa desde cero.

¿Qué diferencia hay entre api-design-principles y un prompt genérico de IA?

Un prompt genérico puede generar endpoints plausibles, pero api-design-principles le da a tu agente un marco de revisión mucho más preciso. Empuja hacia un modelado consistente de recursos, una semántica correcta de métodos, buenos códigos de estado, paginación y una estructura de esquema más sólida. Eso normalmente se traduce en menos limpieza después del primer borrador.

¿Cuándo encaja mal api-design-principles?

Es mejor omitirla cuando tu necesidad principal es:

• generación de código para muchos frameworks
• guía específica de protocolos fuera de REST o GraphQL
• requisitos de compliance propios de tu organización
• diseño profundo de auth o de arquitecturas event-driven

En esos casos, el contenido de la api-design-principles guide puede seguir siendo útil, pero no debería ser tu única fuente de verdad.

¿La skill ayuda con APIs existentes, o solo con diseños greenfield?

Sí. Uno de sus mejores usos es la revisión de APIs ya planteadas o la limpieza de legados. Pásale tus endpoints actuales o fragmentos del esquema y pídele una lista priorizada de problemas de diseño, riesgos de compatibilidad hacia atrás y mejoras de bajo riesgo.

¿Esta skill toma partido por REST o por GraphQL?

Soporta ambos, pero no con la misma profundidad de implementación. La guía REST está reforzada por la checklist y por una plantilla de código, mientras que la parte de GraphQL es más fuerte en patrones de esquema y ejemplos de diseño que en configuración de runtime. Si necesitas scaffolding ejecutable para GraphQL, tendrás que apoyarte en herramientas adicionales.

Cómo mejorar la skill api-design-principles

Da contexto real del dominio, no sustantivos abstractos

La forma más rápida de mejorar la salida de api-design-principles es describir entidades y flujos reales. “Users manage projects and invoices” funciona mejor que “build a business API.” Los dominios concretos permiten a la skill tomar mejores decisiones sobre límites de recursos, nesting y forma de las mutations.

Especifica qué necesitan hacer los clientes con más frecuencia

El diseño de una API debe seguir el uso real. Dile a la skill:

• las rutas de lectura principales
• las operaciones de escritura más habituales
• qué filtros importan
• si los clientes necesitan operaciones masivas
• si importan el ancho de banda en móvil o las integraciones de terceros

Esto cambia materialmente la salida. Por ejemplo, un uso intensivo de list filtering y sparse retrieval orienta el diseño REST de forma distinta a consultas de dashboard muy variables, que pueden favorecer GraphQL.

Pide tradeoffs, no solo un borrador

Muchas salidas flojas vienen de pedir “un diseño de API” sin preguntar por qué. Mejora los resultados con prompts como:

• “Propose two designs and compare tradeoffs.”
• “Flag any endpoint that violates REST semantics.”
• “Explain why fields are nullable or non-null in GraphQL.”
• “Show where versioning will hurt us later.”

Esto obliga a la skill a mostrar el razonamiento en vez de generar contratos pulidos, pero frágiles.

Usa las categorías de la checklist como prompts de revisión

Si la primera salida es genérica, itera por secciones:

• “Revise only resource naming and URL hierarchy.”
• “Now review status codes and error format.”
• “Now add pagination, filtering, and sorting rules.”
• “Now review versioning and deprecation.”

El archivo de checklist es eficaz porque convierte la calidad en dimensiones revisables, en lugar de dejarla en una petición vaga de “hazlo mejor”.

Vigila los fallos más habituales

Los principales fallos al usar api-design-principles install correctamente pero obtener una salida débil son:

• faltan restricciones del dominio
• no hay contexto sobre el cliente objetivo
• se pide REST y GraphQL a la vez sin un objetivo claro de decisión
• no se indican requisitos de compatibilidad para APIs existentes
• no se dan ejemplos de la forma de payload esperada

Esto suele llevar a recursos genéricos, nesting incómodo, manejo de errores difuso y diseños de esquema superficiales.

Valida las salidas contra tus restricciones reales

Antes de adoptar cualquier propuesta de api-design-principles for API Development, comprueba:

• ¿tu modelo de auth puede soportar estas operaciones?
• ¿tus clientes necesitan IDs y timestamps estables en todas partes?
• ¿las colecciones están paginadas por defecto?
• ¿la forma de los errores coincide con las convenciones de la plataforma?
• ¿el versioning encaja con tu proceso de release?
• ¿los campos anulables en GraphQL son intencionales?

La skill mejora la calidad del diseño, pero el contrato sigue siendo responsabilidad de tu equipo.

Mejora la adopción en el equipo con un estándar de revisión ligero

Si quieres obtener valor duradero, convierte la skill en una práctica de equipo:

• usa la checklist en pull requests de especificaciones de API
• exige justificación para las decisiones de versioning y pagination
• documenta una convención de nombres para recursos y mutations
• revisa un archivo de referencia al introducir patrones nuevos

Así api-design-principles usage se vuelve repetible, en vez de quedarse como un prompt puntual que solo sabe usar una persona del equipo.