Primeros pasos con Spectral (Parte 4) : Guía de Estilo de APIs

Publicado por Víctor Madrid el

Arquitectura de SolucionesSpectralAPI LinterDesarrollo APIGuía de EstiloStyle Guide

En este cuarto artículo de Spectral aprenderemos a implementar la herramienta como una guía de estilos de APIs con diferentes enfoques.

cabecera---Enmilocalfunciona---Spectral---1400x400px-3

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

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

Spectral para implementar Guías de Estilo para APIs

Disponer de una guía de estilo para el diseño / desarrollo de APIs dentro de una compañía permite que se diseñen las API de forma estándar, normalizada, homogénea y con aplicación de buenas prácticas. Hay que tener en cuenta que todo lo anterior se corresponde con la forma de hacerlo dentro de esa compañía en particular, de esta forma las APIs adquirirán cierta calidad y seguridad a la hora de desarrollar cualquier funcionalidad.

Ayuda

Se conseja volver a leer lo explicado en el tercer artículo:

En este tipo de documentación se suelen explicar muchas cosas:

  • Relaciones entre recursos
  • Tipos de endpoints: recursos y/o funcionalidad
  • Nomenclatura
  • Uso de verbos HTTP
  • Códigos de estado
  • Uso de paginación
  • Uso de internacionalización
  • Gestión de errores
  • Cabeceras
  • Versionado
  • Respuestas
  • Testing
  • Seguridad
  • Documentación
  • ...

Importante: Hay que tener en cuenta que sobre cada uno de los puntos anteriores se pueden trabajar sus propias buenas prácticas.

Conjuntos de Reglas Corporativas y sus enfoques

Importante

Este apartado aplica sobre cualquier guía de estilo que se quiera desarrollar, aunque posteriormente en el ejemplo lo aplicaremos sobre una guía de estilo de APIs

Asi que antentos a apartado de enfoques

Disponer de conjuntos de reglas corporativos adaptados a las guías de estilos es uno de los aspectos que hace que una compañía se diferencie de otra aun haciendo lo mismo.

Esto significa varias cosas:

  1. Se tiene claro que se quiere
  2. Se tiene claro que se tiene
  3. Se tiene claro que NO se permite

Aprovechando la características de personalización de reglas de Spectral podremos implementar su definición y uso de forma particular.

Se pueden establecer diferentes enfoques:

  • Enfoque de implementación de las reglas
  • Enfoque del ámbito del conjunto de reglas específico
  • Enfoque de definir un conjunto de reglas base
  • Enfoque de distribución de las reglas

Enfoque de implementación de las reglas

Existen diferentes maneras sobre la forma de implementar una regla

  • "single-file": Cada regla se implementa en un fichero independiente
    • Cumplimiento del patrón PSR
    • El fichero debería de llevar el nombre de la regla como ayuda a localizarlo
    • El fichero se podrá almacenar en una estructura definida para ello
      • Global al proyecto
      • Local al proyecto
    • Referenciado desde el fichero de Ruleset utilizado
  • "group": Se implementan varias reglas en un mismo fichero
    • Agrupación por funcionalidad o contexto (Ejemplo: trabajar con https, trabajar con números, trabajar con paginación, etc.)
    • El fichero debería de llevar el nombre de la funcionalidad o contexto referido
    • El fichero se podrá almacenar en una estructura definida para ello
      • Global al proyecto
      • Local al proyecto
    • Referenciado desde el fichero de Ruleset utilizado
  • "ad-hoc": Cada regla se implementa de forma directa sobre el propio fichero de Ruleset

Enfoque del ámbito del conjunto de reglas específico

Existe la posibilidad de disponer diferentes conjuntos de reglas con diferentes criterios de aplicación de reglas

Por ejemplo:

  • Tipología de API
    • APIs de sistemas críticos
    • APIs de arquitecturas Event-Driven
    • APIs de sistemas legacy
    • ...
  • Contexto de uso
    • Aplicaciones legacy
    • Nuevos desarrollos
    • Productos
    • ...
  • Sector sobre el que aplica
  • Tecnología sobre la que aplica
    • Para APIs definidas por OAS v3
    • Para ficheros de configuración YAML de Spring-Boot
    • ...
  • ...

Enfoque de definir un conjunto de reglas base

Se aconseja disponer de un conjunto de reglas que sea aprobado de forma corporativa para uso dentro de la compañía.

Para ello se aconseja definir uno o varios conjuntos de reglas base que pueda aplicar de forma común a todos los proyectos tipo implicados.

Estos conjuntos de reglas requerirán un tratamiento de proyecto de desarrollo como cualquier otro, es decir, van a requerir mantenimiento, testing, versionado, documentación, formación etc.

Ventajas:

  • Disponer de un mismo conjunto de reglas centralizados
    • Uso total o parcial de las reglas -> Uso
      • Extensión de reglas
      • Activación o desactivación de reglas
      • Composición de reglas
      • ...
    • Facilita que cada uno se pueda montar su batería de reglas de validación
  • Evitando que se tenga que re implementar algo 1000 veces
  • Compartir su uso entre proyectos
    • Todo el mundo se evaluaría por las mismas reglas
  • Reducción de tiempos de desarrollo
  • ...

Desventajas:

  • Requiere invertir recursos en este punto :
  • Nunca dejará de evolucionar, por lo tanto, se trata como un proyecto orgánico
  • Requiere un análisis previo para no añadir errores de inicio
  • Un fallo en una de estas guías tras su implementación requerirá mucho mantenimiento correctivo
  • ...

Enfoque de distribución de las reglas

Existen diferentes formas de distribuir las reglas y por lo tanto, hay que te tener definido todo lo necesario para su uso.

Nota

Este es un tema tan importante que el propio fabricante proporciona un enlace de documentación

Algunas impementaciones de la distribución de reglas son:

  • Proporcionar una copia del fichero de configuración y las reglas
  • Proporcionar el fichero de configuración y las reglas de forma centralizada

Proporcionar una copia del fichero de configuración y las reglas

Se proporcionarán de forma sencilla los ficheros necesarios para que cada proyecto lo implemente y lo utilice como quiera.

No se podrá tener el control de quién lo utiliza y quien no.
No se podrá tener el control

Proporcionar el fichero de configuración y las reglas de forma centralizada

Se proporcionarán desde una ubicación central

Existen diferentes formas de implementarse:

  • Incorporar los ficheros como funcionalidad desde una librería de arquitectura del framework de desarrollo
  • Incorporar los ficheros en el arquetipo del proyecto
    • Directorio de configuración: spectral/
    • Fichero por defecto : .spectral.yml
  • Publicar los endpoints de acceso al fichero de configuración y de reglas
    • En la documentación se referencia como "HTTP Server" e indica que se puede hacer uso

Ejemplos de ficheros de Spectral

En este a partado se proporcionarán algunos ejemplos de uso

Ejemplo de fichero Ruleset con reglas base como fichero con enfoque de "extensión"

extends:
    # Usar las reglas predefinidas para OpenAPI
    - spectral:oas
    
    # Extender las reglas con una regla específica definida de forma local
    - ./spectral/rules/open-api-version-3.yaml
    
    # Extender las reglas con un conjunto de reglas corporativo
    - ./global/organization-rules.yaml
    
rules: {
    operation-tags-alphabetical: false
}

Ejemplo de fichero Ruleset con reglas base como fichero con enfoque de "único uso"

extends:
    # Extender las reglas con un conjunto de reglas corporativo
    - ./global/organization-rules.yaml
rules: {
    operation-tags-alphabetical: false
}

Ejemplo de fichero Ruleset con reglas base referenciado desde una URL

extends:
  - https://raw.githubusercontent.com/vjmadrid/enmilocalfunciona-spectral/main/style-guide/spectral/rulesets/company-rules.yaml

Guías de Estilo de Desarrollo de APIs de las Empresas

Cada compañía / equipo / desarrollador tiene su propia forma de hacer las cosas y muchas veces se publican sus guías de estilo de APIs como muestra de transparencia.

Pero esto no se pueden confirmar del todo ...jejeje

Recursos

Spectral proporciona un portal para ayudar con el tema de las guías de estilo

Algunos ejemplos de guías de estilo públicas son:

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 style-guide/

Conclusiones

Continuamos avanzando en nuestro conocimiento sobre Spectral y cada vez le vamos encontrando más utilidades o bien vamos complicando los casos de uso para sacarle más provecho.

A la vez que hacemos lo anterior y casi sin darnos cuentas estamos mejorando la forma de trabajar a nivel de empresa. Además, estamos consiguiendo una de las cosas más interesante que buscan las empresas ... la industrialización de procesos. Estamos incluyendo entonces el proceso lintado como automatismo para diferentes casos de uso.

Además este proceso no sólo ayuda al desarrollo sino que también ayudamos a

  • QA: Añadiendo una capa de validaciones extra sobre el proyecto y su desarrollo que podrá ser medido como un nuevo aspecto de calidad como puede ser la ejecución de test unitarios
  • DevOps: Añadiendo una fase extra dentro del ciclo de CI/CD para evitar propagar errores en producción

Asi que seguiremos mejorando todo esto con los siguientes artículos. ;-)

Continuamos dando pasitos...

Autor

Víctor Madrid

Líder Técnico de la Comunidad de Arquitectura de Soluciones en atSistemas. Aprendiz de mucho y maestro de nada. Técnico, artista y polifacético a partes iguales ;-)