En este tercer artículo de Spectral aprenderemos a usar esta herramienta para el desarrollo específico de APIs

A modo de recordatorio pongo los enlaces a los artículos :

• Primeros pasos con Spectral (Parte 1) : Artículo de introducción a la herramienta Spectral que hace uso de diferentes ejemplos y que explica diferentes enfoques de diseño.
• Primeros pasos con Spectral (Parte 2): Implementar una Regla Custom: Artículo que enseñará la forma de crear una regla customizada y usarla mediante una propuesta de procedimiento sobre la forma de hacerse.
• Primeros pasos con Spectral (Parte 3): Desarrollando APIs: Artículo que enseñará a como enfocar Spectral al desarrollo de APIs.

Cuando se explicó el primer artículo ya hablamos de la problemática de hacer código en ciertos lenguajes sin una guía de estilo.

Desarrollar APIs no se iba a salvar de esto, como se compone de código también existe la posibilidad de:

• Generar inconsistencias
• Existir diferentes estilos de API según su tipología
• Existir diferentes estilos de un mismo API dentro de una organización
• Incorporar vulnerabilidades de seguridad
• Incorporar errores de funcionalidad
• Incorporar errores que rompen la interfaz
• Generar problemas directos sobre los desarrollos de los clientes
• Etc.

Por lo tanto, existen muchas maneras de hacer un API... y sobre todo de hacerlas mal jejeje

Este es el índice que se va a utilizar para estructurar este artículo

• Desarrollo de APIs
• Spectral para desarrollo de APIs
• Spectral como Guías de Estilo para APIs
• Ejemplo de Uso
• Conclusiones

Desarrollo de APIs

Hay que tener en cuenta que las acciones/prácticas de diseño de API en una compañía también evolucionan con el tiempo. Y este es un punto muy importante a tener en cuenta, aunque se termine el desarrollo eso no evita que no se tenga que volver a tocar.

Aspectos a tener en cuenta:

• Especificaciones para el desarrollo de APIs
• API Linting
• Revisiones de APIs

Especificaciones para el desarrollo de APIs

Existen diferentes especificaciones para el desarrollo de APIs.

Las más utilizadas son las siguientes:

• OpenAPI (OAS aunque también se suele conocer como Swagger)
• AsyncAPI
• RAML (RESTful API Modeling Language)

Aclaración

Una especificación de API tiene como objetivo definir un formato de descripción de un API que sea entendible por un humano e interpretable por una máquina

Se hará uso de la especificación seleccionada para crear un documento que sirva como descripción de un API

Este documento tiene dos formas de crearse :

• Desarrollo a mano o ad-hoc
• Desarrollo a partir de código

Además, este documento suele tener un formato de representación según la especificación seleccionada.

Para el caso de un documento OpenAPI sus formatos de representación pueden ser:

• JSON
• YAML (opción más recomendada)

Ejemplo de fichero OpenAPI v3 en formato JSON

{
  "openapi": "3.1.0",
  ...
}
...

Ejemplo de fichero OpenAPI v3 en formato YAML

openapi: 3.1.0
# A comment
...

Se considera una buena práctica incorporar una acción lintado durante su desarrollo/diseño para verificar la validez del API.

A esta acción se la denomina API Linting

API Linting

Proceso o acción opcional dentro del ciclo de desarrollo de un API que se encarga de:

• Comprobar que el API se encuentra bien definida técnicamente
  • Versión de la especificación utilizada
  • Información general sobre el API (nombre, versión, etc.)
  • Paths definidos y sus operaciones
  • Entradas de sus operaciones
  • Salidas de error
  • Uso de seguridad
  • ...
• Comprobar que el API verifica una serie de condiciones / restricciones que vienen dada por una guía de estilo para el desarrollo de APIs
  • Errores
  • Problemas de seguridad
  • Definiciones
  • Valores por defecto
  • Cabeceras
  • Documentación de las partes
  • Nomenclatura
  • *... *

Este proceso es un claro candidato a ser automatizado para su uso: durante el desarrollo, integración en CI/CD, etc.

El objetivo por tanto de este proceso será el de generar un documento
estandarizado, homogeneizado y compatible con la especificación seleccionada.

Mejoras del API Linting

Con este proceso se conseguiría mejoras en :

Coherencia
El API utilizado tendrá un formato que se va a regir por una guía de estilos definida, la cual además cumplirá tras realizar una validación sobre ella.

Estas guías permiten reducir enorme los errores al tener la mayoría de ellos ya identificados.

Con esto uno de los puntos que mejora es la documentación de las APIs y se le dota de la característica de fiabilidad, es decir, ganamos en confianza de lo que hemos hecho y este aspecto no es ninguna tontería.

Mantenimiento
Los desarrolladores al tener ese formato de desarrollo de APIs definido, validado, establecido y explicado, leerán y entenderán con mayor facilidad cada API.

Gracias a la experiencia de hacer las cosas de la misma manera permitirá la detección temprana de problemas o incoherencias que es cuando menor coste tiene el resolverlas. Además, se permitirá acelerar los siguientes desarrollos muchísimo porque ya se sabe cómo empezar y porque se tiene mucho hecho.

Se mejorará también el mantenimiento correctivo al incrementarse la velocidad para detectar elementos con error, obsoletos o no compatibles.

Autonomía de los desarrolladores
Como aspecto que sale beneficiado de los dos anteriores surge la autonomía de los desarrolladores, ahora que se sabe que hay menos posibilidades de fallar y que existe un validador que avisará si la liamos mucho, podemos realizar más y mejores mantenimientos correctivos y evolutivos.

Calidad
Al disponer de una guía de estilo definida se podrá disponer entonces un elemento documental que además tiene definido los criterios de calidad actuales sobre nuestras APIs.

Esto nos abre la posibilidad de disponer de diferentes conjuntos de reglas que representan la calidad según nuestras necesidades. Por ejemplo: disponer de un enfoque más estricto para las aplicaciones más críticas y otro más laxo para las aplicaciones legacy.

Al tener los criterios de calidad por escrito esto puede ayudar a encontrar mejoras en todo lo que ya tenemos definido -> Mejora continua

Estas reglas de calidad se pueden actualizar según las necesidades de la compañía, sector o de forma global.

En aquellas compañías donde se realicen revisiones de calidad estas se verán mejoradas con la reducción de los tiempos de su realización, en la cantidad de revisiones realizadas y en el nº de personas con conocimiento para hacerlas, en no tener cuellos de botella por su disponibilidad, etc.

Seguridad

Al tener definida la guía de calidad y el conjunto de reglas se detectar desde fases tempranas posibles fallos de seguridad del API (autenticación y autorización) al realizar pruebas sobre el código

Con lo que estaríamos dando pasitos en el concepto de SAST (Static Application Security Testing)

Automatización

Se puede mejorar enormemente el proceso de testing y validación al poder automatizarlo de forma sencilla.

Si lo conseguimos conseguiremos de forma directa ahorro de tiempo, ahorro de esfuerzo y una mejora importante de la calidad

Por automatización se puede valorar su incorporación:

• En el ciclo de vida del desarrollo
  • Adelantaría la detección de errores al tiempo de desarrollo, es decir, mientras se escribre la especificación
  • Integración con el IDE o uso de plugins
• En el ciclo de CI/CD
  • Detener la construcción si se detecta algun error
  • Se añade como paso extra en el proceso CI/CD
  • Dependerá del proceso de CI/CD
  • Se hará necesario hacer uso de alguna herramienta o complemento para gestionar los errores y suspender la compilación
• En la elaboración de herramientas que puedan generar clientes sobre un API dado, generación de arquetipos, etc.
• ...

Revisiones de APIs

He podido comprobar con la experiencia de muchos años en el sector de la consultoría que realmente existen muy pocas personas con la capacidad real de hacer validaciones de la guía de estilo de API sobre los desarrollos.

Inicialmente esta validación se realiza de forma manual y presenta los siguientes "problemas" a tener en cuenta:

• Requiere mucho tiempo para hacerse
• En muchos casos esta validación no se encuentra procedimentada
  • Quizás exista un Excel o Word con un checklist de cada uno de los aspectos considerados
• No se puede hacer siempre que se quiera porque tienen un coste alto interno (parar el desarrollo, el coste de la persona que hace la validación, la planificación, etc)..
• Existen pocas personas que lo puedan hacer para la cantidad de APIs que tiene en desarrollo una compañía
• Las personas que lo realizan están siempre muy ocupadas
• Las personas según el grado de inspiración puede cometer errores -> fallos humanos
• Los desarrollos de las APIs suelen tener más cambios que la cantidad de revisiones que se requieren

Aun con todas estas pegas, esto se puede hacer y hay veces que esto puede funcione más o menos bien dentro de una compañía.

Tener en cuenta que disponer de un API Linting automatizado o con partes automatizadas ya mejorarían muchos de los problemas enumerados anteriormente.

Spectral para desarrollo de APIs

Spectral se convierte en la herramienta ideal para implementar API linting en una compañía ya que funciona como linter de propósito general sobre diferentes tipos de documentos.

Para el caso de las APIs solo se necesita usar el conjunto de reglas adecuado y trabajar con un formato de representación JSON y/o YAML

Aspectos a tener en cuenta:

• Reglas por defecto para APIs
• Personalización de reglas para APIs
• Spectral como Guía de Estilo para APIs

Reglas por defecto para APIs

Spectral proporciona dos conjuntos de reglas por defecto para *APIs:

• spectral:oas: Se usa para reglas OpenAPI v2/v3
  • Reglas que incluye
    • oas3-recommended: Conjunto de reglas consideradas de "buenas prácticas" para la especificación OpenAPI 3.0
    • oas3-security: Conjunto de reglas consideradas de "seguridad" para la especificación OpenAPI 3.0
    • ...
• spectral:asyncapi: Se usa para reglas AsyncAPI v2
  • Reglas que incluye

Esto es genial debido a que la propia herramienta proporciona estos conjuntos de reglas que ya están alineados con las especificaciones más utilizadas en el mercado. Por lo tanto y para el caso del "API linting" estas ya se pueden utilizar desde el momento en el que se ha instalado la herramienta.

Hay que tener en cuenta que nada exige que se tengan que cumplir sus reglas en su totalidad por lo que se puede personalizar cada una de las reglas ya existentes (activando, desactivando, cambiando la severidad), también se puede no utilizar ninguna de las ya existentes y/o se pueden extender nuevas reglas que se adapten a la compañía y/o proyecto como uno quiera o necesite.

Personalización de reglas para APIs

Una de características más importantes de la herramienta es la capacidad de poder personalizar la definición del conjunto de reglas a aplicar.

Facilita la incorporación de nuevas reglas o su adaptación a lo largo del tiempo y según las necesidades particulares de la organizacion.

Tener esta opción disponible en la herramienta facilita la evolución del diseño de APIs con el tiempo a al vez que evoluciona la compañía

Para temas de personalización quizás sea de ayuda el volver a revisar el segundo artículo:

• Primeros pasos con Spectral (Parte 2) : Implementar una Regla Custom : Artículo que enseñará la forma de crear una regla customizada y usarla mediante una propuesta de procedimiento sobre la forma de hacerse.

Spectral como Guía de Estilo para APIs

Recordatorio

Disponer de una guía de estilo para el desarrollo de APIs dentro de una compañía permite que se diseñen las API de forma estándar y homogénea, de esta forma las APIs adquirirán cierta calidad y seguridad a la hora de desarrollar

Ya le hemos dado muchas vueltas a este tema y hemos visto muchos de los puntos que se puede mejorar. Ahora la pregunta será ¿Y por donde empiezo a plantear esto?

Pues tendremos que esperar al siguiente artículo donde hablará de esto en detalle ;-)

Ejemplo de Uso

Para enseñar a utilizarlo y así practicar se ha habilitado un repositorio, este repositorio se reutilizará para otros artículos con Spectral.

La parte de que tiene que ver con este artículo se encuentra en el apartado de api-development/

En el fichero README.md de esta sección nos encontraremos los diferentes escenarios de prueba utilizados en el apartado Uso, conviene entender muy bien las explicaciones de cada uno de ellos.

Se han añadido a modo de extra varias reglas que podrían venir bien en el análisis de APIs

Se pueden ver más ejemplos recordando los ejemplos realizados en los artículos

• Primeros pasos con Spectral (Parte 1) : Artículo de introducción a la herramienta Spectral que hace uso de diferentes ejemplos y que explica diferentes enfoques de diseño.
• Primeros pasos con Spectral (Parte 2): Implementar una Regla Custom: Artículo que enseñará la forma de crear una regla customizada y usarla mediante una propuesta de procedimiento sobre la forma de hacerse.

Conclusiones

Con todo el conocimiento que acumulamos en este tercer artículo ya podemos plantearnos seriamente incorporar esta herramienta para el API linting de nuestra compañía.

En este artículo hemos podido ver su aplicación sobre las APIs y cuáles, son sus puntos fuertes. Por lo tanto, parece que tiene más ventajas que inconvenientes, señal de que nos va a evitar más de un lagrima futura.

Por otro lado, a todos que os encanta el enfoque API-First pero ...

• ¿Cuántos lo aplicáis con garantías?
• ¿Veis Spectral como pieza esencial para poder aplicarlo bien?

Atentos al siguiente artículo en el que hablaremos sobre las formas en las que podremos implementarlo como guía de estilo corporativa.

Continuamos dando pasitos...