Escuela de APIs
Calidad de las Apis
Conoce como evaluar la calidad de tus apis utilizando nuestras reglas de spectral tanto para openapi como para asyncapi
¿Qué es Spectral?
Spectral es una herramienta de código abierto de linting para APIs que permite validar y verificar la calidad de las definiciones de APIs de manera automática. Actúa como un «linter» especializado que analiza los documentos de especificación de API (como OpenAPI/Swagger o AsyncAPI) y aplica un conjunto de reglas configurables para detectar problemas, inconsistencias y malas prácticas.
¿Cómo usar Spectral para comprobar la calidad de tus APIs en tiempo real?
Spectral te permite verificar en tiempo real la calidad de tus APIs de la siguiente manera:
- Instalación: Instala Spectral mediante npm con el comando
npm install -g @stoplight/spectral-cli - Configuración: Crea un fichero
.spectral.yamlen tu proyecto donde defines el ruleset que quieres aplicar a tus definiciones de API. - Ejecución: Ejecuta Spectral contra tu especificación OpenAPI o AsyncAPI con el comando
spectral lint openapi.yaml - Integración CI/CD: Integra Spectral en tus pipelines de CI/CD para validar automáticamente cada cambio en las definiciones de tus APIs antes de que lleguen a producción.
- Resultados en tiempo real: Spectral te muestra al instante los errores, advertencias e informaciones sobre la calidad de tu definición de API, indicando el número de línea y la descripción del problema.
Con Spectral puedes asegurarte de que todas tus APIs cumplen con los estándares de calidad y las buenas prácticas definidas por tu organización, reduciendo errores y mejorando la consistencia entre equipos.
Reglas de buenas prácticas de la Fundación APIAddicts
La Fundación APIAddicts genera y mantiene conjuntos de reglas (rulesets) basados en buenas prácticas para ayudar a los equipos de desarrollo a garantizar la calidad de sus APIs. Estas reglas se organizan en tres grandes categorías:
- Validación de la definición de especificación: Verifica que el documento de especificación cumpla con los estándares definidos por las organizaciones de estandarización (OpenAPI Initiative, AsyncAPI Initiative), asegurando que la estructura, los campos obligatorios y los tipos de datos sean correctos y estén bien definidos.
- Validación de la definición de API: Comprueba que el diseño de la API sigue las mejores prácticas de diseño RESTful o asíncrono, incluyendo la correcta nomenclatura de endpoints, uso adecuado de métodos HTTP, respuestas bien documentadas, paginación, versionado y otros aspectos de diseño críticos para una API de calidad.
- Validación basada en seguridad: Verifica que la definición de la API incluye los mecanismos de seguridad necesarios, como esquemas de autenticación (OAuth2, API Keys, JWT), definición correcta de scopes, protección de endpoints sensibles y otras buenas prácticas de seguridad que deben estar documentadas en la especificación.
Estas reglas están disponibles como rulesets de Spectral, lo que permite a cualquier equipo integrarlas fácilmente en sus flujos de trabajo y validar automáticamente la calidad de sus definiciones de API tanto para OpenAPI como para AsyncAPI.
sonar-openapi-rules
sonar-asyncapi-rules
Principales características de sonar-openapi-rules
El ruleset sonar-openapi-rules de APIAddicts proporciona un conjunto completo de reglas para validar definiciones OpenAPI. A continuación se presentan sus principales características:
- Validación de estructura: Verifica que todos los campos obligatorios de la especificación OpenAPI estén presentes y correctamente definidos, incluyendo info, paths, components y servers.
- Naming conventions: Aplica convenciones de nomenclatura consistentes para paths, operaciones, parámetros y esquemas, asegurando coherencia en toda la API.
- Documentación completa: Comprueba que todas las operaciones, parámetros y esquemas tengan descripciones detalladas que faciliten la comprensión de la API por parte de los consumidores.
- Seguridad: Verifica la correcta definición de los mecanismos de seguridad, incluyendo esquemas de autenticación, scopes y la aplicación de seguridad en los endpoints sensibles.
- Manejo de errores: Valida que todos los endpoints documenten correctamente las respuestas de error estándar (4xx, 5xx), mejorando la robustez de la API.
- Compatibilidad con SonarQube: Las reglas están diseñadas para integrarse con SonarQube y otras herramientas de análisis de calidad, permitiendo visualizar los resultados en dashboards centralizados.
- Extensibilidad: El ruleset puede ser extendido o personalizado para adaptarse a las necesidades específicas de cada organización, añadiendo reglas propias al conjunto base.
¿Quieres conocer las mejores prácticas para APIs?
Aprende las mejores prácticas para el diseño, desarrollo y gobernanza de APIs con nuestros cursos especializados. Formación práctica impartida por expertos de la industria.
