NOR_MICROS v01r00

Ámbito de aplicación de la norma

Esta norma se aplica tanto a nuevos desarrollos como a mantenimientos que incluyan la creación o modificación de microservicios.

Las directrices que contiene la norma son independientes de la pila tecnológica que se utilice. Los objetivos y características de la arquitectura no están vinculados a la tecnología de implementación. 

Por tanto, al implementar un microservicio con una tecnología específica, hay que cumplir con:

• Las normas y estándares referidos en esta página.
• Otras normas particulares establecidas para dicha tecnología.

Diseño

Nomenclatura y definición de APIs y sus operaciones

DIR_01 Estándar de nomenclatura de URIs

OBLIGATORIO Las URIs de las operaciones seguirán una serie de reglas estándar para su nomenclatura:

• Deben usar solo los verbos GET, POST, PUT, PATH y DELETE:
  • GET: obtener información del servidor.
  • POST: crear un nuevo recurso y, por consiguiente, modifica el estado del servidor.
  • PUT: actualizar un recurso.
  • PATCH: actualizar parte de un recurso .
  • DELETE: eliminar un recurso.
• Deben estar orientadas a la exposición de recursos y no de operaciones. Por ejemplo: /usuarios/{dni}/informes/{idInforme} 
• La nomenclatura de los campos y parámetros debe estar en formato lowerCamelCase.
• Los nombres de la URI no deben implicar una acción, por lo tanto, no se podrán usar verbos en ellos.
• Han de ser únicas y no debe haber más de una URI para identificar un mismo recurso.
• Deben mantener una jerarquía lógica según el aspecto de negocio que trate:
  • Por ejemplo: la URI /facturas/25/clientes/007 no sería una URI correcta, ya que no sigue una jerarquía lógica de negocio ya que la factura está asociada al cliente y no al revés. 
  • Para el recurso factura con el identificador 25 del cliente 007, la siguiente URI sería la correcta: /clientes/007/facturas/25.
• Los filtrados de información de un recurso no deben hacerse en la URI. Se realiza concatenando atributos.
• Los QueryParam y PathParam no deben contener datos sensibles. En el caso de necesitar enviar datos sensibles, se enviarán dentro del body. Si se trata de una consulta obligatoriamente se debe configurar como un POST.
• Las fechas deben tener el siguiente formato: YYYY[MM[DD[HH[mm[ss]]]]].
• Se debe incluir la versión de la API en la uri: /v1/usuarios.

DIR_02 Versionado de cambios no retrocompatibles

OBLIGATORIO Se creará una nueva versión de la API si se han realizado cambios que afectan al contrato de los servicios (no retrocompatibles).

Se consideran cambios no retro compatibles:

• Eliminar operaciones o acciones sobre un recurso. Ejemplo: Ya no se aceptan peticiones POST sobre un recurso.
• Añadir nuevos parámetros de entrada obligatorios. Ejemplo: Ahora para dar de alta un recurso hay que enviar en el cuerpo de la petición un nuevo campo requerido.
• Modificar parámetros de entrada de opcional a obligatorio. Ejemplo: Ahora al crear un recurso Persona, el campo edad, que antes era opcional, ahora es obligatorio. 
• Modificar o eliminar un parámetro en operaciones (verbos sobre recursos) ya existentes. Ejemplo: al consultar un recurso ya no se devuelve determinado campo. Otro ejemplo: un campo que antes era una cadena de caracteres ahora es numérico. 
• Añadir nuevas respuestas en operaciones ya existentes. Ejemplo: ahora la creación de un recurso puede devolver un código de respuesta 412.

DIR_03 Mantenimiento de versiones retro compatibles

OBLIGATORIO El microservicio aceptará las peticiones de las versiones anteriores de la API, por retro compatibilidad, hasta que se decida eliminarlas.

Convenciones sobre la estrategia de diseño de los servicios

DIR_04 Adopción de la estrategia API-FIRST

OBLIGATORIO Se adoptará una estrategia de desarrollo api-first: primero definición del servicio y luego desarrollo.

Hay que definir en un contrato con las operaciones, métodos y datos del negocio del servicio como fase inicial del análisis, para implementar posteriormente el código.

https://swagger.io/resources/articles/adopting-an-api-first-approach/

DIR_05 Principio de responsabilidad única en microservicios

RECOMENDADO Los microservicios seguirán el principio de Responsabilidad Única para garantizar que cada servicio tenga una única razón para cambiar.

Para seguir la recomendación de Responsabilidad Única en el diseño de microservicios, estos deben tener una única responsabilidad o función definida.

• Evitar la sobrecarga de funcionalidades.
• Ser simples y fáciles de entender para facilitar su mantenimiento.
• Descomponer funcionalidades complejas en microservicios más pequeños y especializados.
• Evitar la lógica de negocio duplicada entre diferentes microservicios.
• No mezclar responsabilidades de diferentes dominios en un mismo microservicio.
• Garantizar que cada microservicio se centre en una capacidad de negocio específica.

DIR_06 Principio de Fuente Única de Dato

RECOMENDADO Para garantizar que cada microservicio acceda a una única fuente de datos autorizada y coherente, seguirán el principio de Fuente Única de Dato.

Para conseguir la Fuente Única de Datos en el diseño de microservicios, estos deben:

• Obtener datos de una fuente de datos centralizada y autoritativa.
• Evitar duplicar datos en diferentes microservicios para mantener la coherencia y evitar inconsistencias.
• Implementar APIs de acceso a datos para permitir que otros microservicios accedan a la fuente de datos de manera controlada y segura.
• Garantizar que los datos en la fuente única sean consistentes y estén actualizados en todo momento.
• Separar los datos por dominio de negocio para evitar la interdependencia entre diferentes microservicios.
• Establecer mecanismos de validación y control de la integridad de los datos para mantener su calidad y confiabilidad.
• Ser capaz de escalar y gestionar cargas variables para satisfacer las necesidades de los microservicios.

Acceso a los servicios

DIR_07 Acceso a microservicios siguiendo patrón Api Gateway

OBLIGATORIO El acceso a los microservicios desde el exterior seguirá un patrón de Api Gateway para centralizar y gestionar el acceso a los servicios de backend, garantizando un punto de entrada único y seguro para las solicitudes.

Se debe consultar el Modelo de Despliegue Microservicios correspondiente a la tecnología con la que se construya el Microservicio, puesto que existen casos en las que la aplicación de este patrón está delegada en la infraestructura.

DIR_08 Políticas de balanceo

OBLIGATORIO Se establecerán las políticas de Load Balancing para que distribuyan las solicitudes entrantes entre múltiples instancias de un servicio para evitar la sobrecarga en cualquier instancia individual.

En la configuración de los servicios statefull su política de Load Balancing tendrá en cuenta la conservación del estado.

Se consultará el Modelo de Despliegue Microservicios correspondiente a la tecnología con la que se construya el Microservicio, puesto que existen casos en las que la aplicación de esta política esté delegada en la infraestructura.

Resiliencia de los servicios

DIR_09 Incorporación de políticas de resiliencia

RECOMENDADO Las políticas de resiliencia se considerarán como una parte integral de la arquitectura y el diseño de sistemas distribuidos, especialmente en entornos de microservicios. Es recomendable implementar un conjunto diverso de políticas de resiliencia en cada servicio para mitigar una variedad de posibles fallas y errores.

Existen casos de uso en los que la aplicación de algunas de estas políticas pueda estar delegada en la infraestructura.

Las posibles políticas de resiliencia a incluir serían:

• Circuit Breaker: se definirán las políticas de Circuit Break para detectar y manejar errores en servicios remotos de una manera eficiente. 
• Fallbacks: se recomienda definir las políticas de Fallbacks para tener planes de contingencia en el caso de que un servicio principal no está disponible.
• Timeouts:  se definirán las políticas de Timeout para establecer límites de tiempo para las solicitudes a servicios remotos, evitando los bloqueos y manteniendo la capacidad de respuesta del sistema.
• Retries: se recomienda definir las políticas de Retries para ayudar a recuperarse de fallas temporales en las llamadas a servicios remotos y mejorar la disponibilidad del servicio. Es una política que debe de implementarse con cuidado para evitar la sobrecarga del sistema, por lo que se recomienda su uso exclusivamente en servicios críticos o en casos donde las fallas transitorias sean comunes.
• Bulkheads: se recomienda definir las políticas de bulkheads de forma que aíslen partes críticas del sistema y limitar el impacto de las fallas. Esto ayuda a prevenir la propagación de errores y garantiza la disponibilidad continua del sistema.

Construcción

Tipos de comunicación

DIR_10 Uso de OpenAPI en comunicación síncrona

OBLIGATORIO En el caso de comunicación síncrona, es necesario el uso de OpenAPI como estándar para definir las APIs. Además, las comunicaciones se realizarán con alguno de los siguientes protocolos:

• API REST: Método estándar que debe ser utilizado en la mayoría de los proyectos, proporcionando consistencia y claridad en la definición de las APIs.
  • En aquellos casos en los que históricamente los servicios web de un sistema de información sean SOAP y el cambio tecnológico implique un esfuerzo desproporcionado con los beneficios del cambio, se mantendrán los desarrollos de servicios SOAP. Para ello, es necesario contar con el visto bueno de la Oficina de Arquitectura de Soluciones.
• GraphQL: Se puede recomendar su uso en proyectos que necesitan proporcionar métodos de búsqueda y exploración de los datos publicados, permitiendo consultas complejas y precisas para acceder a la información.
• gRPC síncrono: Se puede recomendar su uso en proyectos que requieren alta velocidad y eficiencia en la comunicación entre servicios, especialmente en entornos donde se prioriza la comunicación síncrona con bajo tiempo de latencia.

Se tendrá en cuenta que OpenAPI puede adaptarse para describir APIs basadas en GraphQL o gRPC, aunque es posible que no cubra todas las características específicas de estos protocolos. Por lo tanto, se recomienda realizar una evaluación detallada para asegurarse de que la descripción de la API se ajuste adecuadamente al protocolo utilizado. 

En el caso de que se haya permitido el uso de SOAP, se usará el patrón de diseño XML Schema y no debe contener parámetros con XML incrustado.

DIR_11 Uso de AsyncAPI en comunicación asíncrona

OBLIGATORIO En el caso de comunicación asíncrona, es necesario el uso de AsyncAPI como estándar para definir las APIs. Además, las comunicaciones se realizarán con alguno de los siguientes protocolos:

• SSE (Server-Sent Events): Se recomienda su uso en proyectos que requieren una transmisión unidireccional de eventos desde el servidor al cliente de manera eficiente y en tiempo real.
• WebSocket: Se recomienda su uso en proyectos que necesitan una comunicación bidireccional y en tiempo real entre el cliente y el servidor.
• gRPC asíncrono: Se recomienda su uso en proyectos que demandan una alta velocidad y eficiencia en la comunicación asincrónica entre servicios, especialmente en entornos donde se prioriza la comunicación asíncrona con bajo tiempo de latencia.

Se tendrá en cuenta que AsyncAPI puede adaptarse para describir APIs basadas en SSE, WebSocket o gRPC asíncrono, aunque es posible que no cubra todas las características específicas de estos protocolos. Por lo tanto, se recomienda realizar una evaluación detallada para garantizar que la descripción de la API se ajuste adecuadamente al protocolo utilizado.

Mantenibilidad y calidad

DIR_12 Adopción de la arquitectura hexagonal

RECOMENDADO Se valorará la aplicación del patrón de arquitectura hexagonal.

Para conseguir una correcta aplicación de la Arquitectura Hexagonal al diseño de microservicios, estos deben:

• Tener una clara separación entre los puertos (interfaces) que definen las funcionalidades de la aplicación y sus adaptadores (implementaciones concretas).
• Tener los puertos (interfaces) definidos por la aplicación, mientras que los adaptadores (implementaciones) deben depender de estos puertos, siguiendo el principio de inversión de dependencias.
• Existir un aislamiento de la lógica de negocio, residiendo en el núcleo de la aplicación, sin depender de detalles de implementación tecnológica.
• Implementar, en cada adaptador, una única responsabilidad relacionada con la conexión entre la lógica de negocio y un elemento externo, evitando la sobrecarga de funcionalidades en un solo adaptador.

Para una correcta aplicación de la norma, en la implementación el proyecto se definirían las siguientes capas:

• Dominio: Esta capa representa el núcleo de la aplicación, donde se definen los objetos y servicios que encapsulan las reglas de negocio. Aquí se encuentran las entidades, agregados y servicios de dominio que reflejan el modelo conceptual de la aplicación.
• Repositorio: La capa de Repositorio se encarga de interactuar con las fuentes de datos externas, como bases de datos o servicios web. Aquí se definen las interfaces y clases concretas que permiten la persistencia y recuperación de datos del dominio, manteniendo la lógica de acceso a los datos separada de la lógica de negocio.
• Aplicación: En la capa de Aplicación se definen los casos de uso de la aplicación, que representan las acciones que los usuarios pueden realizar. Aquí se implementa la lógica de coordinación entre los objetos del dominio y los servicios de infraestructura, utilizando los servicios de dominio y los repositorios necesarios para cumplir con los requisitos de los casos de uso.
• Rest: La capa Rest se encarga de exponer las APIs del microservicio a través de interfaces RESTful, permitiendo la comunicación con clientes externos. Aquí se definen los controladores REST que reciben las solicitudes HTTP, gestionan la entrada de datos, y dirigen las llamadas a los casos de uso correspondientes en la capa de Aplicación.
• Boot: Esta capa se encarga de la configuración y el inicio de la aplicación. Incluye la inicialización de frameworks, la configuración de componentes de infraestructura como bases de datos o sistemas de mensajería, y la gestión de dependencias. Su objetivo es preparar el entorno de ejecución de la aplicación antes de que comience la lógica de negocio.

La comunicación entre las diferentes capas de la arquitectura hexagonal debe realizarse exclusivamente a través de objetos e interfaces definidos en la capa de Dominio.

DIR_13 Granularidad en la organización de microservicios

RECOMENDADO Es necesario buscar un equilibrio entre el número de servicios y operaciones, evitando la definición del servicio con una excesiva granularidad de operaciones.

Se diseñarán servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables. Puede tomarse como un buen punto de partida el definir un Servicio Web por cada servicio de negocio identificado. Se recomienda no sobrepasar las cinco operaciones por servicio.

DIR_14 Externalización de la configuración

RECOMENDADO Las configuraciones no sensibles de los servicios se recomienda gestionarlas dinámicamente de forma externa a la definición del microservicio.

Para una correcta aplicación de la norma se tendrán las siguientes posibilidades:

• Herramienta de configuración centralizada que proporciona una gestión centralizada de la configuración para aplicaciones distribuidas, permitiendo almacenar la configuración de manera externa y ofreciendo una forma fácil de distribuir y actualizar la configuración en tiempo de ejecución.  
  La herramienta de configuración centralizada depende de la tecnología de implementación del microservicio y por lo tanto definido el documento Modelo de Despliegue Microservicios correspondiente.
• ConfigMaps de Kubernetes que proporciona una forma de desacoplar la configuración del contenedor de las imágenes de aplicación, lo que facilita la gestión de la configuración y su modificación sin necesidad de cambiar el código fuente de la aplicación.

La Herramienta de Configuración Centralizada será la opción prioritaria para establecer la configuración de forma externa a la definición de Microservicio y los Modelos de Despliegue Microservicios correspondiente a la tecnología con la que se construya el Microservicio podrán dar indicaciones para utilizar herramientas corporativas.

Anexo: Estándares

Definición de servicios y eventos

• Open API
• Async API
• WSDL
• XML Schema

Comunicaciones

• API RESTful
• GraphQL
• gRPC
• WebSockets
• Server-Sent Events (SSE)

Seguridad

• SSOWEB(SAML 2.0)
• HTTPS/SSL
• OAuth2