Norma para el desarrollo de servicios de interoperabilidad

Á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 servicios de integración interoperables.

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

Por tanto, al implementar una integración en 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

Reglas y convenciones para la nomenclatura de los servicios y operaciones y para el versionado de las APIs que las exponen

DIR_01 Nomenclatura de las URI de las operaciones

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

• DEBEN usar solo los métodos GET, POST, PUT, PATCH 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 de estar orientadas a la exposición de recursos y no de operaciones. /usuarios/{dni}/informes/{idInforme}
• DEBEN usar nomenclatura de campos y parámetros lowerCamelCase. 
• DEBEN usar plurales en los nombres. /usuarios y no /usuario 
• Las URI NO DEBEN implicar una acción, por lo tanto, no se podrán usar verbos en ellas. 
• Han de ser únicas, 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 con QueryParam.
  • Incorrecto: /facturas/anio/2024/total/500-1000
  • Correcto: /facturas?anio=2024&total_min=500&total_max=1000
• Los QueryParam y PathParam NO DEBEN contener datos sensibles. En el caso de necesitar enviar datos sensibles, se enviarán dentro del body (si es una consulta, se DEBE configurar como un POST).
• Las fechas DEBEN tener el siguiente formato: YYYY[MM[DD[HH[mm[ss]]]]]
• NO DEBE incluir la versión de la API en la uri: /usuarios/v1/, salvo en casos concretos que tendrán que obtener el visto bueno de la OTI.
• Se DEBE usar el castellano como idioma para definir las operaciones.

DIR_02 Versionado y retrocompatibilidad

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

Cambios no retrocompatibles:

• 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 Retrocompatibilidad

OBLIGATORIO El servicio aceptará las peticiones de las versiones anteriores de la API, por retrocompatiblidad, hasta que se decida eliminarlas.

Convenciones sobre la estrategia de diseño de los servicios

DIR_04 Estrategia API-first

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

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

• Enfoque API-first

Reglas para la distribución de carga

DIR_05 Balanceo de carga

OBLIGATORIO Se establecerán políticas de balanceo de carga para que distribuyan las solicitudes entrantes entre múltiples instancias de un servicio, de tal forma que se evite la sobrecarga en cualquier instancia individual.:

Los servicios statefull DEBEN configurar su política de balanceo de carga teniendo en cuenta la conservación del estado.

Es necesario consultar el Modelo de Despliegue de la arquitectura, puesto que existen casos en las que la aplicación de esta política esté delegada en la infraestructura y, por lo tanto, sólo será necesario la configuración en dicho componente para que se active el balanceo de carga al servicio.

Reglas relacionadas con la resiliencia de los servicios

DIR_06 Resilencia

OBLIGATORIO Se incluirán las siguientes políticas de resiliencia:

• Circuit Breaker: se DEBEN definir 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 DEBEN definir 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

Reglas y convenciones relacionadas con el tipo de comunicación

DIR_07 Comunicación síncrona

OBLIGATORIO En el caso de comunicación síncrona, se utilizará la especificación OpenAPI en su versión 3.1.X como estándar para definir las APIs. Además, las comunicaciones se establecerán con alguno de los siguientes protocolos:

• APIs 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 RECOMIENDA 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 RECOMIENDA 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 DEBE tener 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 DEBE  usar el patrón de diseño XML Schema, NO DEBEN existir parámetros que contengan XML incrustado, se DEBE usar la cabecera Content-Type "application/soap" o "apllication/soap+xml", se DEBE utilizar siempre la misma versión de especificación o versiones compatibles y se RECOMIENDA el uso de mecanismos de transmisión como MTOM (Message Transmission Optimization Mechanism) para la transmisión de ficheros.

DIR_08 Comunicación asíncrona

OBLIGATORIO En el caso de comunicación asíncrona, se utilizará 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.

Reglas y convenciones relacionadas con la estructura de los proyectos

DIR_09 Composición de los proyectos de interoperabilidad

OBLIGATORIO Los proyectos de servicios de interoperabilidad cumplirán las siguientes pautas.

• Existirá un proyecto "parent" compuesto por los siguientes artefactos:
  • Composite Application Project (Capp)
  • ESB Config Project (CP)
  • Registry Resource Project (RP)
  • Data Services (DSS)
• Todos los artefactos DEBEN tener el mismo groupId en el fichero pom.xml, que será es.juntadeandalucia.ada.interoperabilidad
• En el elemento modules del fichero pom.xml del proyecto parent, DEBEN estar todos los componentes del desarrollo siendo el CApp el último de la lista.
• El proyecto parent DEBE incluir una carpeta "Profile" que permita definir el valor de las variables del proyecto completo en función del entorno (perfil) correspondiente.
• El proyecto parent DEBE incluir un fichero changelog.md, que incluya información acerca del versionado de cada versión del código.
• El proyecto parent DEBE incluir un fichero README.md, que incluya información acerca del proyecto.

DIR_10 Nomenclatura de artefactos y componentes

OBLIGATORIO La nomenclatura del proyecto parent y sus artefactos seguirá esta serie de reglas estándar.

• Parent: Servicios[Intranet/Extranet][ACRONIMONombreServicio]Parent, donde ACRÓNIMO son las siglas del organismo/sistema proveedor del servicio, que se informa para facilitar la ubicación conceptual del código fuente
• Composite Application Project (Capp): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_CApp
• ESB Config Project (CP): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_CP
  • Nomenclatura API/PROXY: [INT/EXT]_[PUB/PRV]_[NombreServicio]_v[X] donde:
    • Visibilidad: INT (Interno) / EXT (Externo). Los servicios cuyo nombre empiecen por INT son solo accesibles desde la RCJA. Los EXT son accesibles desde dentro y desde fuera de la RCJA.
    • Autenticación: PUB (No tiene autenticación) / PRV (Es necesario autenticarse para consumir el servicio)
    • NombreServicio: Nombre del servicio a publicar. En caso de nombres compuestos, SE DEBE utilizar UpperCamelCase. Ejemplo: INT_PUB_ServicioEjemplo_v1
    • v[X]: versión de la api/proxy
  • Nomenclatura secuencias de flujo para PROXY: [INSEQUENCE/OUTSEQUENCE/FAULTSEQUENCE]_[SOAP]_[NOMBRESERVICIO]_v[X]
  • Nomenclatura secuencias de flujo para API: [INSEQUENCE/OUTSEQUENCE/ FAULTSEQUENCE]_[NOMBRESERVICIO]_[METODO]_[NOMBRERECURSO]_v[X]
• Registry Resource Project (RP): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_RP
  • Ruta física=Ruta lógica: [REST/SOAP]/[Sistema]/[NombreParent]/[vx.y.z]/comun/[endpoints/wslds/...]
  • Nomenclatura endpoint:[NombreServicio]_Endpoint.xml (Si una API tuviera varios endpoint, SE DEBEN diferenciar según funcionalidad (recurso, método...))
  • Nomenclatura scripts: [NombreServicio]_[Funcionalidad]_Scripts.xml
  • Nomenclatura wsdl: [NombreServicio].wsdl
  • Nomenclatura xsd: [referencia original del xsd].xsd
• Data Services (DSS): Servicios[Intranet/Extranet][ACRONIMONombreServicio]_DSS
  • Nomenclatura dataservice:[NombreServicio]ServicioDSS.dbs

Reglas y convenciones para facilitar la mantenibilidad y calidad del servicio

DIR_11 Verificación de la calidad del código

OBLIGATORIO El equipo de desarrollo aplicará un mecanismo de verificación de la calidad del código que se ejecute de forma continua o frecuente, minimizando el número de defectos y reduciendo la deuda técnica.

En aquellos casos en los que sea técnicamente viable, se utilizarán los siguientes Umbrales de aceptación permitidos por SonarQube Quality Gates.

Se RECOMIENDA la instalación de forma local de este conjunto de reglas en los IDEs del equipo de desarrollo para ir monitorizando en tiempo real su cumplimiento y garantizar la resolución instantánea en caso de detección de no conformidades.

DIR_12 Conformidad con la calidad

OBLIGATORIO El equipo de desarrollo mantendrá en niveles mínimos el número de no conformidades respecto a las normas de calidad del código.

En nuevos desarrollos, se cumplirán, cuando estén definidos, los umbrales de aceptación, desde las primeras versiones de código.

En el caso de un sistema preexistente, se establecerá una línea base en la primera entrega, que será considerada como el nivel máximo de no conformidades, cuyo número se debe ir reduciendo.

DIR_13 Versionado

OBLIGATORIO Se utilizará la política de versionado SEMVER (Versionado Semántico).

De cara a garantizar que todos los productos o componentes software sigan una política de versionado estándar, se deben aplicar las pautas marcadas por el esquema de control de versiones SEMVER, que se resumen a continuación:

• El software que use Versionado Semántico DEBE declarar un elemento de infraestructura, configuración o despliegue. Este, puede ser declarado en el código mismo o existir en documentación estricta que, de cualquier manera, debería ser precisa y completa.
• Un número normal de versión DEBE tomar la forma X.Y.Z donde X, Y, y Z son enteros no negativos. X es la versión “major”, Y es la versión “minor”, y Z es la versión “patch”. Cada elemento DEBE incrementarse numéricamente en incrementos de 1. Por ejemplo: 1.9.0 -> 1.10.0 -> 1.11.0.
• Una vez que un paquete versionado ha sido liberado (release), los contenidos de esa versión NO DEBE ser modificados. Cualquier modificación DEBE ser liberada como una nueva versión.
• La versión major en cero (0.y.z) es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento. El elemento NO DEBE ser considerada estable.
• La versión 1.0.0 define el elemento. La forma en que el número de versión es incrementado después de este release depende de este elemento y de cómo cambia.
• La versión patch Z (x.y.Z | x > 0) DEBE incrementarse cuando se introducen solo arreglos compatibles con la versión anterior. Un arreglo de bug se define como un cambio interno que corrige un comportamiento erróneo.
• La versión minor Y (x.Y.z | x > 0) DEBE ser incrementada si se introduce nueva funcionalidad compatible con la versión anterior. Se DEBE incrementar si cualquier funcionalidad del elemento es marcada como deprecada. PUEDE ser incrementada si se agrega funcionalidad o arreglos considerables al código privado. Puede incluir cambios de nivel patch. La versión patch DEBE ser reseteada a 0 cuando la versión minor es incrementada.
• La versión major X (X.y.z | X > 0) DEBE ser incrementada si cualquier cambio no compatible con la versión anterior es introducido en el elemento. PUEDE incluir cambios de nivel minor y/o patch. Las versiones patch y minor DEBE ser reseteadas a 0 cuando se incrementa la versión major.

De forma resumida:

• X: Aumentará cuando se producen cambios que rompan la compatibilidad de alguna manera con la versión anterior. (major).
• Y: Aumentará con cada funcionalidad añadida compatible con la versión anterior. (minor).
• Z: Aumentará con correcciones compatibles con la versión anterior. (patch).

Para más información sobre SEMVER:

• SEMVER (Versionado Semántico)

DIR_14 Repositorio de código fuente

OBLIGATORIO El mensaje de subida de cambios al repositorio de código debe seguir las siguientes pautas.

La nomenclatura del mensaje del commit debe ser “ADD/UPDATE/FIX #id Comentario de funcionalidad añadida, actualizada o corregida”, donde:

• ADD indica que se añade funcionalidad
• UPDATE indica que se actualiza una funcionalidad existente
• FIX indica que se realiza un correctivo sobre una funcionalidad existente
• #id es el identificador de la tarea de TEO en la que se describen los trabajos a realizar

DIR_15 Nomenclatura de propiedades

OBLIGATORIO La nomenclatura de las propiedades definidas en el fichero de propiedades deberán seguir las siguientes pautas.

La nomenclatura de la propiedad será “[cpv/rpv/dss].[tipo_parametro].nombre_parametro”, donde:

• CPV indica que hace referencia a una propiedad del Config Project
• RPV indica que hace referencia a una propiedad del Repository Project
• DSS indica que hace referencia a una propiedad del Data Services Project
• Tipo_parametro, por ejemplo, ep si hace referencia a un endpoint del backend
• Nombre_parametro siguiendo la convención snake case

DIR_16 Tiempo de respuesta máximo

OBLIGATORIO El tiempo de respuesta máximo del servicio tendrá que ser acordado y coherente con las especificaciones del mismo.

Se DEBE acordar un tiempo de respuesta máximo del servicio acorde con las especificaciones del mismo. Si el proveedor no lo indica, se establecerá por defecto a 30s.

DIR_17 Granularidad de operaciones

RECOMENDADO Se evitará la definición del servicio con una excesiva granularidad de operaciones, buscando un equilibrio entre el número de servicios y operaciones.

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

DIR_18 Configuración externa

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

Para ello, se 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.

Se almacenarán datos de configuración que no cambian con frecuencia, como variables de entorno y archivos de configuración. Esto permitirá una gestión centralizada y dinámica de la configuración. NO DEBEN contener información sensible.

Por ejemplo, uso de los ConfigMaps de Kubernetes para almacenar datos de configuración.

Políticas para la gestión de errores

DIR_19 Errores

OBLIGATORIO Se definirá una política que gestione los errores para cubrir al completo los posibles escenarios que puedan producirse. Cubrirá tanto errores de carácter técnico, desacoplados del servicio y de la arquitectura del sistema, como errores funcionales derivados del propio tratamiento del mensaje.

Esta política debe tenerse en cuenta a la hora de diseñar e implementar los servicios que proporcionan los sistemas de información.

• Errores de comunicación: relativos al envío y aceptación de los mensajes por parte del sistema receptor de la misma. Los receptores de la mensajería deberán realizar una validación sintáctica del esquema, valores de los campos y formato.
• Errores técnicos de la aplicación: producidos durante el procesamiento (caídas de bbdd, código mal desarrollado, errores de SO, no controlados, …)
• Errores funcionales de la aplicación: derivados del tratamiento de la información contenida en el mensaje aceptado por el sistema proveedor.

SE DEBE usar los códigos de error de forma coherente con el tipo de error (mal uso de errores técnicos en funcionales). Por ejemplo, ante una consulta GET en la que no se encuentran datos, sería incorrecto devolver un 404 Not Found. En su lugar, habría que devolver un 204 No Content.

SE DEBE registrar y manejar los errores de manera segura, evitando la exposición de detalles técnicos que puedan ser aprovechados por posibles atacantes para comprometer la seguridad de la aplicación.

Se RECOMIENDA que sólo se de por finalizada la operación cuando se haya recibido confirmación de la entrega. Para ello, todos los servicios DEBEN tener una respuesta para verificar que el mensaje se ha entregado correctamente y además cumple con unas validaciones mínimas.

Observabilidad

Monitorización

DIR_20 Uso de las secuencias de monitorización

OBLIGATORIO Se deben usar las secuencias de monitorización genéricas implementadas para mostrar los indicadores de negocio.

Las secuencias implementadas que hay que usar en función del tipo de servicio (REST o SOAP) para cada petición, respuesta o fallo son las siguientes:

• En la inSequence la secuencia de monitorización de la petición: 
  • Servicios REST: 
    • SEQ_COMUN_MONITORIZAR_REQUEST_API
  • Servicios SOAP: 
    • SEQ_COMUN_MONITORIZAR_REQUEST
• En la outSequence, la secuencia de monitorización de la respuesta:
  • Servicio REST: 
    • SEQ_COMUN_MONITORIZAR_RESPONSE_API
    • SEQ_PUBLISHEVENT_MONITORIZAR_API
  • Servicio SOAP: 
    • SEQ_COMUN_MONITORIZAR_RESPONSE
    • SEQ_PUBLISHEVENT_MONITORIZAR_PROXY
• En la faultSequence, la secuencia de monitorización del fallo:
  • Servicios REST: 
    • SEQ_COMUN_MONITORIZAR_FAULT_API
  • Servicios SOAP: 
    • SEQ_COMUN_MONITORIZAR_FAULT

Estas secuencias SE DEBEN referenciar de la siguiente forma: <sequence key="gov:/servicios/Comunes/Secuencias/[NombreSecuencia].xml" />

En el caso de que el desarrollo contenga validaciones, SE DEBE añadir una referencia a la secuencia de la faultSequence, ya que en caso de que falle la validación del mensaje se deberá mostrar dicho error.

Pruebas

Políticas de pruebas sobre sistemas de integración

DIR_21 Pruebas unitarias

OBLIGATORIO Se realizarán suficientes pruebas unitarias para cubrir el mínimo porcentaje exigido de código, validando todos los componentes elementales y sus distintas rutas lógicas.

Las pruebas unitarias son la primera línea de defensa en la detección de errores, por lo que es muy importante que cubran la mayor parte de la lógica de forma aislada del resto.

DIR_22 Pruebas de integración

OBLIGATORIO Se realizarán las pruebas necesarias para comprobar que todos los componentes de la arquitectura de interoperabilidad se integran de manera correcta.

DIR_23 Pruebas de rendimiento

OBLIGATORIO Se realizarán pruebas de rendimiento (carga, picos y estrés) en entornos no productivos para validar que la solución de interoperabilidad implementada es capaz de responder a las necesidades para las que ha sido creada.

Normas relacionadas

La construcción de un microservicio implica el cumplimiento de esta norma y las normas transversales que se apliquen:

• Norma de uso del repositorio de código corporativo
• Norma de uso de la estrategia de ramificación de la plataforma CI/CD corporativa
• Norma de uso del pipeline de integración continua de la Plataforma CI/CD corporativa
• Norma para el alineamiento con la pila tecnológica de la ADA
• Norma para el desarrollo seguro
• Norma para la observabilidad
• Norma para desarrollos Java (obligatorio en microservicios desarrollados en java)

Estándares

El siguiente listado muestra los estándares que se aplican a la arquitectura de microservicios. Puede consultarse la descripción de cada estándar en la siguiente página

Definición de servicios y eventos

• Open API
• Async API
• XML Schema

Comunicaciones

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

Seguridad

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