api-design-framework
Diseña APIs coherentes con plantillas OpenAPI
Los equipos de API suelen perder tiempo resolviendo rutas, errores, versiones y documentación inconsistentes. Esta skill proporciona patrones prácticos, listas de verificación y plantillas para trabajos con REST, GraphQL, gRPC, OpenAPI y AsyncAPI.
Descargar el ZIP de la skill
Subir en Claude
Ve a Configuración → Capacidades → Skills → Subir skill
Activa y empieza a usar
Recursos legibles por agentes
Usa estos enlaces cuando un AI Agent, crawler o script necesite contexto limpio en lugar de leer toda la página.
Pruébalo
Usando "api-design-framework". Diseña una API REST de gestión de usuarios para una herramienta interna de administración.
Resultado esperado:
- Un modelo de recursos con usuarios, roles y campos de estado.
- Una lista de rutas con métodos para operaciones de listar, crear, leer, actualizar y eliminar.
- Una estrategia de respuesta que cubre paginación, errores de validación, errores de autenticación y límites de tasa.
Usando "api-design-framework". Revisa este diseño de mutación GraphQL antes de la implementación.
Resultado esperado:
- Una revisión basada en lista de verificación de tipos de entrada de mutaciones, forma del payload, campos anulables y errores a nivel de campo.
- Una lista de cambios de contrato que mejoran la experiencia del cliente y la compatibilidad hacia atrás.
- Un conjunto breve de preguntas de seguimiento para decisiones de producto o seguridad sin resolver.
Usando "api-design-framework". Documenta eventos del ciclo de vida de pedidos para un bus de mensajes.
Resultado esperado:
- Un esquema orientado a AsyncAPI con canales, operaciones, mensajes, esquemas de payload y esquemas de seguridad.
- Recomendaciones para IDs de evento, IDs de correlación, marcas de tiempo, idempotencia y comportamiento de reintento.
Auditoría de seguridad
Riesgo bajoStatic analysis reported many high-risk patterns, but review found they are documentation examples, API route snippets, schema fields, and placeholder service URLs. No executable scripts, command execution, credential exfiltration, prompt injection, or malicious intent were found. The remaining low risk is that example URLs and auth placeholders must be customized before production use.
Problemas de riesgo bajo (3)
Factores de riesgo
Puntuación de calidad
Lo que puedes crear
Crear una nueva API REST pública
Usa las convenciones y la plantilla OpenAPI para definir endpoints, errores, autenticación, límites de tasa y documentación antes de la implementación.
Revisar un contrato de API antes de construirlo
Usa la lista de verificación para comparar un contrato propuesto con requisitos de nombres, versionado, manejo de errores, rendimiento y lanzamiento.
Documentar servicios basados en eventos
Usa la plantilla AsyncAPI para describir canales, payloads y esquemas de seguridad basados en Kafka, RabbitMQ, WebSocket o mensajes.
Prueba estos prompts
Ayúdame a elegir REST, GraphQL o gRPC para este servicio. Pregunta por los requisitos faltantes y luego recomienda un estilo de API con ventajas y desventajas.
Diseña endpoints REST para este modelo de recursos. Incluye rutas, métodos, códigos de estado, paginación, filtrado, errores y versionado.
Revisa este contrato de API según la lista de verificación de diseño de API. Identifica inconsistencias, documentación faltante, brechas de seguridad y bloqueadores de lanzamiento.
Crea un plan de documentación OpenAPI o AsyncAPI para este servicio. Incluye esquemas, operaciones, esquemas de seguridad, ejemplos, errores y notas de despliegue.
Mejores prácticas
- Empieza con requisitos, usuarios, propiedad de los datos y estilo de API antes de nombrar endpoints.
- Mantén coherentes los formatos de error, la paginación, la autenticación y el versionado entre servicios.
- Reemplaza todas las URLs, contactos, ejemplos y esquemas de seguridad de marcador de posición antes de publicar la documentación.
Evitar
- No copies endpoints ni credenciales de plantilla en producción sin revisión.
- No mezcles convenciones de nombres, significados de códigos de estado ni formatos de error dentro de una misma API.
- No diseñes cambios incompatibles sin versionado, avisos de obsolescencia y guía de migración.