Solución de servicios apificados

La aplicación de esta solución tecnológica es dependiente de la disponibilidad de la Plataforma de APIs. Se puede consultar la fecha de disponibilidad en la hoja de ruta

¿Cuándo utilizarla?

Finalidad y casos de uso

Esta solución está orientada a la publicación de APIs que engloban servicios que vayan a ser consumidos por distintos canales, sistemas o equipos dentro de la Junta de Andalucía. 

Al exponer funcionalidades o datos a través de APIs, los servicios pueden integrarse fácilmente y adaptarse a nuevos contextos, como aplicaciones móviles, plataformas web o integraciones automatizadas, sin duplicar esfuerzos ni crear procesos redundantes. 

Algunos casos en los que podría utilizarse son:

  • Integración de servicios de identidad digital:   
    Cuando varios sistemas de información (por ejemplo, salud, educación) necesitan validar la identidad de una persona, una API de identidad digital permitiría centralizar y reutilizar este proceso. Así, en lugar de pedir a la ciudadanía que entregue sus datos una y otra vez, los sistemas consultan directamente y de forma segura esa información.

  • Interoperabilidad para consulta de datos necesarios para evaluar la concesión de una ayuda o subvención:   
    Para otorgar beneficios como subsidios, becas o ayudas, es común que distintos organismos necesiten verificar datos (ingresos, situación laboral, composición familiar). A través de APIs, estas verificaciones pueden hacerse en tiempo real, evitando que las personas tengan que presentar documentación física o repetir trámites en diferentes oficinas.

  • Notificaciones unificadas al ciudadano:   
    Un servicio apificado puede centralizar el envío de notificaciones oficiales (como avisos de pago, recordatorios o citas) a través de diferentes canales (correo electrónico, SMS, aplicaciones móviles). Así, cualquier sistema público que necesite informar algo importante puede usar la misma API, asegurando que la comunicación sea coherente, segura y rastreable.

Características y ventajas 

  • Interoperabilidad: Permite que diferentes sistemas se comuniquen y compartan información de forma estandarizada.
  • Acceso seguro y controlado: A través de mecanismos de autenticación, autorización y cifrado basados en roles y permisos, así como el uso de credenciales o certificados.
  • Reutilización de funcionalidades: Expone capacidades (como validación de identidad, pagos, notificaciones) que pueden ser usadas por múltiples aplicaciones.
  • Modularidad: Separa las funcionalidades en partes que se pueden actualizar o cambiar sin afectar todo el sistema.
  • Escalabilidad: Puede adaptarse dinámicamente a la demanda y atender picos puntuales de solicitudes.
  • Limitación de accesos: Evita la pérdida de servicios críticos por accesos menos prioritarios.
  • Disponibilidad a través de internet o redes privadas: Los servicios pueden ser consumidos desde distintos entornos según la necesidad.
  • Estándares abiertos: Basada en protocolos que facilitan la adopción y la integración.
  • Trazabilidad y monitorización: Permite registrar y auditar el uso que se hace de los servicios, garantizando transparencia y seguridad.
  • Gestión de errores: Manejo de la indisponibilidad de algún componente del sistema.

Detalle técnico

Solución de servicios apificados
  1. El API Manager permite la publicación y consumo de servicios de backend de forma centralizada. A las API publicadas en este componente se le aplican ciertas políticas de forma generalizada entre las que figuran seguridad, límite de acceso u observabilidad.
  2. Las API necesitan un soporte en servicios backend cuyo cometido es implementar la lógica del servicio que publican. Lo habitual es utilizar microservicios. Algunas de las operaciones habituales que implementa una API son:
    • Acceso a las fuentes de datos para lectura y escritura de datos
    • Acceso al bus de interoperabilidad para consumir o enviar datos a servicios de interoperabilidad con otros sistemas
    • Envío y consumo de eventos para operaciones asíncronas y reacción a eventos para ejecución de procesos o tareas automáticas
  3. Pueden existir distintos tipos de orígenes de datos en función de las necesidades de almacenamiento y acceso a los datos
  4. Opcional El bus de interoperabilidad se utilizará en los casos en los que la API publicada deba integrarse con un sistema que publica sus servicios de interoperabilidad en el bus.
  5. Opcional Los servicios apificados pueden interactuar con el broker de mensajería en los casos en los que los servicios de backend que implementan el API necesiten enviar o consumir eventos de algún tópico para efectuar operaciones asíncronas o reaccionar a eventos para ejecutar procesos internos.

 

Cómo adaptarla a tu caso concreto

Preparación del entorno de desarrollo

Para configurar el equipo local, lee la guía de desarrollo de api y la guía de desarrollo de microservicios donde verás las herramientas que están a tu disposición y las normas que debes seguir.

 

Adaptación

Para adaptar esta solución a tu caso concreto debes:

  1. Definir el contrato de la API según se ha establecido en las normas de diseño de API y la arquitectura de referencia
  2. Definir el diseño del microservicio teniendo en cuenta la norma de diseño de microservicios y la arquitectura de referencia

Para la construcción de la API:

  1. Del listado de plantillas que próximamente estará disponible, ejecutar la plantilla que más se adapte a las necesidades de desarrollo de la solución.
  2. A partir del diseño inicial, modificar el fichero generado por la plantilla con la especificación del contrato de la API.

Para la construcción del microservicio (usando el framework de desarrollo ada-fwk-ms):

  1. Del listado de arquetipos publicados por el framework, ejecuta el arquetipo que más se adapte a las necesidades de desarrollo del microservicio. Recomendamos utilizar el arquetipo fwk-apifirst-archetype o fwk-crud-apifirst-archetype. Los arquetipos recomendados generarán un microservicio completamente funcional que publica una API siguiendo la implementación api-first.
  2. Sustituye el fichero con la especificación de contrato generado por el arquetipo por el creado por el desarrollador durante la construcción de la API.
  3. Siguiendo las instrucciones indicadas en el módulo del framework fwk-swagger, configura el plugin de Maven openapi-generator-maven-plugin para que se generen correctamente las clases java que implementan el contrato definido en el microservicio.
  4. Añade los módulos del framework necesarios para implementar el negocio. Para ello se recomienda revisar el listado de módulos disponibles en el framework.
  5. Compila el microservicio utilizando el comando maven mvn clean install. Al compilar el microservicio y haber configurado el plugin openapi-generator-maven-plugin, se generarán las clases necesarias para implementar el contrato de la API y se descargarán del artifactory de la Junta de Andalucía las dependencias tanto del framework como de librerías de terceros necesarias para la correcta ejecución del microservicio.
  6. Siguiendo las instrucciones publicadas en el módulo del framework fwk-swagger, implementa la API a partir del contrato definido y utilizando los objetos autogenerados por el plugin openapi-generator-maven-plugin de Maven.
  7. Implementa el negocio que dotará de funcionalidad a la API ayudándote de las herramientas proporcionadas por los módulos del framework incluidos en el microservicio.
  8. Implementa la seguridad basada en token para restringir el acceso al microservicio. Se recomienda utilizar el módulo del framework fwk-security y seguir las directrices indicadas en el documento de ##normas de seguridad##.
  9. Configura la observabilidad del microservicio. Para ello asegurarse de que el microservicio está correctamente configurado para poder conectarse con la plataforma de observabilidad. Se recomienda consultar la documentación del módulo fwk-otpl del framework.
  10. Verifica que el microservicio cumple con la normativa referente a logs y que el código tiene configurado el nivel de log correcto. Revisa el fichero logback-spring.xml generado por el arquetipo y verifica que está correctamente configurado para cumplir con las necesidades del proyecto.

 

Para la publicación de la API en el API Manager, se han de revisar una serie de ficheros:

  1. Revisar el fichero con la documentación adicional de la API generado por la plantilla y hacer los cambios necesarios para que se adapte a la solución. Esta documentación abarca entre otros aspectos las guías y manuales de uso de la API. Suele tener un formato menos técnico para que cualquier persona pueda entender claramente el objetivo de la API y la funcionalidad que ofrece.
  2. Revisar los ficheros de configuración de la documentación generados por la plantilla y hacer los cambios necesarios para que se adapte a la solución.
  3. Modificar el fichero de parametrización de la API generado por la plantilla. Dentro de esta parametrización se pueden definir respuestas mocks permitiendo a los equipos de desarrollo utilizar la API en un entorno de desarrollo sin tener que esperar al despliegue del microservicio.

Próximamente se harán públicos y adjuntarán a esta documentación ejemplos de estos ficheros para poder entender la estructura de los mismos.

 

Despliegue

Para desplegar la API revisa el modelo de despliegue de apis.

Para desplegar el microservicio revisa el modelo de despliegue de microservicios.

 

Recursos relacionados

Reglas y pautas

Arquitecturas de referencia

Normas

Activos 

Servicios de Apoyo

Índice
Directo a

Te puede interesar