En la cabecera de web existe el icono “engranaje” y haciendo clic sobre él se despliega un menú con las diferentes pantallas donde se puede acceder.
General #
Desde configuración se puede acceder a “General” donde aparece el nombre de la organización en la que se encuentra. El nombre de la organización se crea cuando se realiza el registro y desde esta pantalla puede ser editado.
En esta pantalla también se puede elegir si quiere mostrar la URL del repositorio y del Mock Server. Para ello, el checkbox debe de estar seleccionado o no y posteriormente guardar lo seleccionado. Debemos tener en cuenta que de forma predeterminada están activos, los mismos se reflejarán en el apartado 6.2.2.
Por último, nos indica el procedimiento para eliminar una organización, facilitando el correo electrónico de soporte APIQuality (support@apiquality.io).
Añadir miembros #
Podemos añadir miembros a nuestra organización se hayan registrado o no previamente en API Quality. A estos miembros se les debe añadir un rol o varios y una colección o varias colecciones a las que se sea que tenga acceso los cuales, es imprescindible para poder finalizar el formulario. Con cada uno de los diferentes roles el miembro podrá realizar diferentes acciones..
Al añadir un miembro ya registrado le llegará un correo electrónico informando que ha sido añadido a una organización.
Al añadir un miembro sin registrar, a este le llegará un correo para que realice el registro y posteriormente otro para que verifique la cuenta. En la pantalla de miembros el estado irá cambiando según el miembro se registre y verifique.
Además, los miembros pueden ser editados así como eliminados si es necesario.
Importar API Template #
En una organización se puede subir uno o varios templete corporativos para que sus desarrolladores puedan acceder a ella a la hora de definir sus APIs y subirlas a la herramienta.
Para ello, se puede acceder a la pantalla “API template” desde el menú de configuración. Al hacer clic “Añadir API template“ se abrirá un formulario y haciendo clic en el botón de Seleccionar fichero se cargará el archivo de definición, siempre que este tenga extensión .yaml, .yml o .json. El cual podremos descargar o eliminar.
Guía de estilos #
Las guías de estilos son el conjunto de reglas que se aplican al escaneo de las APIs.
Por defecto se crea una guía de estilos con el nombre de la organización que se usa de forma predeterminada en todas las colecciones que creemos y que no tengan vinculada una guía de estilos concreta. Aunque se pueden añadir todas las guías que se deseen a tu organización. Todas las guías de estilos tendrán por defecto activadas todas las reglas.
Para crear más guías de estilos, se debe acceder a dicha pantalla desde el menú de configuración y hacer clic en el botón Crear Guía de Estilos.
Dentro del diálogo de creación, se nos pedirá introducir un nombre para la guía de estilos y marcar si queremos que esta nueva guía sea utilizada por defecto en caso de no vincular ninguna a las colecciones de APIs.
Si todo ha ido bien, visualizamos el siguiente aviso:
Si necesitamos realizar cambios en una guía de estilos, podemos modificarla haciendo clic en el icono del lápiz o eliminarla haciendo clic en el icono de la papelera:
Reglas de una guía de estilos #
Las reglas de las guías de estilos analizan las definiciones de APIs, asegurando que sigan estándares específicos y buenas prácticas, garantizando su correcta funcionalidad y coherencia.
Podemos visualizar las reglas que pertenecen a una guía de estilos concreta haciendo clic en su nombre.
Desde esta pantalla, podemos configurar las reglas que se usarán para escanear una API con la guía de estilos seleccionada, modificar los valores de los parámetros en aquellas reglas que así lo permitan, etc.
Podemos activar y desactivar tantas reglas como queramos, teniendo en cuenta que solo podrán editarse aquellas que se encuentren activas.
Dentro del diálogo de edición, podremos modificar la severidad de la regla, así como los parámetros que tenga asociados. Una vez realizados los cambios necesarios, pulsamos en Editar regla para guardar.
Colecciones #
Las colecciones son una forma de agrupar APIs que permite trabajar de forma más sencilla. Es importante tener en cuenta que, las guías de estilos, se aplican sobre una colección por lo que, todas las APIs que pertenezcan a una misma colección, se escanearán con la misma guía de estilos.
Se puede acceder a “Colecciones” desde el menú de configuración. Se pueden crear tantas colecciones como se deseen y en cada una de ellas se pueden agregar todas las APIs necesarias.
Una vez se accede a “Colecciones” desde el menú de configuración, aparece un listado con las colecciones ya existentes, el número de APIs que contiene la colección, la guía de estilo, las calificaciones que tiene la colección y un botón para crear Nueva colección. También podremos editar, actualizar y eliminar la colección deseada.
Cabe destacar que una vez hecho el registro y creada una cuenta con su correspondiente organización también se crea por defecto una colección por lo que, cuando se acceda por primera vez a “Colecciones” aparecerá la primera creada por defecto.
Crear nueva colección #
Para empezar a crear nuevas colecciones hay que hacer clic en el botón Nueva colección.
Una vez se ha hecho clic, se abrirá un formulario donde se nos pedirá introducir un nombre (obligatorio) y seleccionar la guía de estilos que se aplicará en el escaneo de las APIs, así como un apartado de descripción de la misma. Es importante recordar que, si no se selecciona ninguna guía de estilos, se aplicará la que hayamos marcado como predeterminada.
Detalle colección #
Cada una de las colecciones creadas se puede editar o eliminar desde los iconos que aparecen a la derecha de cada colección. Se debe tener en cuenta que no se podrá eliminar una colección que está asociada a una API.
Se puede acceder a la guía de estilos asociada a cada colección creada desde el enlace de dicha guía.
También se puede acceder al detalle de una colección haciendo clic en el enlace de dicha colección.
En el detalle de cada colección se pueden observar todas las APIs que pertenecen a ella y además se pueden crear más mediante el botón Importar API aunque, como veremos en el apartado 6, también podremos hacerlo desde el Explorador de APIs.
Reporte de la colección #
Una vez se ha subido por lo menos una API en la colección y se ha ejecutado la el ciclo de API First, se generará un reporte de la colección, que nos muestra tanto las notas globales de la colección y las notas individuales de cada API.
En la sección de cada API se puede acceder al reporte completo con más información. Sección 6.2.2.1.
Se debe tener en cuenta que hasta que no hayamos asignado una API a nuestra colección, no podremos tener un reporte de colecciones.
Ramas y pipelines #
Se puede acceder a la pantalla “Ramas y pipelines” desde el menú de configuración. En la misma podremos hacer modificaciones del ciclo de API First tanto en desarrollo como en producción. aunque debemos tener en cuenta que en producción solo podremos modificar con que API Manager queremos desplegar.
Editar rama #
Para editar o modificar el ciclo de API First en el entorno de desarrollo, haremos clic sobre el icono de editar, el cual nos llevará a la vista de edición de la rama.
En esta vista, vemos los stages disponibles para incluir en el ciclo de API First, estas herramientas están agrupadas por categorías. Cada herramienta puede añadirse al ciclo, eliminarla del ciclo, editarla y en los casos de Microcks, Sonarqube y Newman se podrá activar o desactivar la puntuación que se calcula. Esta calificación si está activada, será parte de la nota que calculamos para la API.
Editar pipeline #
Dentro de cada rama, podemos editar la pipeline que se ejecutará. Para ello tenemos que hacer clic en el botón de Ciclo de API First.
Se abrirá un editor de texto con el yaml actual de la pipeline y que podemos modificar. Una vez modificada, hacemos clic en guardar los cambios realizados
Editar stage #
Además de editar la pipeline, cada stage se puede modificar dando clic en “Editar stage” dentro del menú de configuración. Al editar se nos abrirá un editor de texto para modificar el yaml que se ejecutará.
Agregar stage #
En el entorno de desarrollo se pueden añadir nuevos stage según las necesidades de la organización. colocaremos nombre y descripción de la misma y escribiremos en el editor de texto el código yml del stage personalizado.
Cuentas #
Se puede acceder a la pantalla “Cuentas” desde el menú de configuración.
En este apartado, por un lado, se pueden vincular las aplicaciones para integrarlas en API Quality y por otro lado se pueden vincular los repositorios para importar APIs desde ellos.
Aplicaciones #
Las aplicaciones que se pueden vincular son GitLab on Premise, SonarQube y Microcks.
Se debe tener en cuenta que para vincular GitLab on Premise no se debe tener ninguna API importada a la organización.
Además, es recomendable primero vincular GitLab on Premise y posteriormente SonarQube y Microcks para el funcionamiento correcto de la aplicación.
Para realizar la vinculación debemos rellenar el modal con los datos requeridos, los cuales son obligatorios.
Repositorios #
Para la vinculación con los repositorios: Gitlab, Github, Azure Devops y Bitbucker. para poder subir APIs desde ellos, haremos clic en el botón de vincular.
Podemos realizar la vinculación de dos formas para los repositorios Gitlab, Github y Azure Devops: Mediante Inicio de sesión en el navegador y Mediante personal access token.
Por el contrario, en BitBucket encontraremos solo la opción de vinculación mediante inicio de sesión en el navegador.
