A continuación, os cuento la información más importante, pasos a seguir y buenas prácticas sobre el uso, configuración y creación de APIs mediante Talend.
A lo largo del documento se presenta una parte más teórica con los conceptos básicos de las APIs (recursos, operaciones, tipos) y una parte práctica de como crear, publicar y utilizar APIs mediante el uso de Talend Studio y Talend Cloud. Todo ello se explica de una manera muy detallada, apto para distintos tipos de perfil (conocimientos básicos sobre Talend), con o sin conocimiento previo a cerca de APIs.
1. Teoría básica APIs en Talend
Cada día es más común encontrar numerosos orígenes y estructuras de datos distintos, que además crecen de manera exponencial. Talend permite manejar las nuevas estructuras de datos provenientes de aplicaciones en la nube, aplicaciones SaaS y aplicaciones locales mediante una solución de negocio completa.
Este proceso consiste en la extracción de datos a partir de distintos Lake o Data Warehouse, realizar sobre ellos un proceso de transformación y gobernanza del dato para poder obtener datos organizados y limpios para poder utilizarlos posteriormente en distintas funcionalidades APIs. Estas APIs permiten compartir la información con otras plataformas o “componentes” de la inteligencia empresarial.
La plataforma Cloud API Services de Talend proporciona un ciclo de desarrollo de APIs completo, desde el diseño hasta el desarrollo final.
· De manera sencilla se puede diseñar, crear prototipos y documentar APIs en Talend API Designer.
· De forma rápida y eficaz se puede utilizar el servicio de Talend Studio para implementar las distintas funcionalidades de la API.
· El proceso de validación y testeo para declarar una API como solida y reutilizable se realiza mediante Talend API Tester.
· El desarrollo de servicios se realiza desde Talend Management Console.
En este documento se presenta una API REST. En este tipo de APIs los servidores y las aplicaciones intercambian mensajes HTTP de tipo GET, POST y DELETE. Se suelen utilizar normalmente como interfaces entre aplicaciones web o móvil y sus back-ends.
En una API se definen tres conceptos principales, recursos, operaciones y tipos de datos. Los recursos son los elementos con los que los consumidores (clientes de la API) interactúan a través de la API. Cada recurso es único y tiene su propia ruta (su propia manera y nombre de acceder hasta él). Las operaciones son las acciones que se realizan sobre los recursos. Las más comunes, como se han mencionado anteriormente, son GET (leer recursos), POST (crear o publicar recursos), PUT (actualizar recursos) y DELETE (borrar recursos). Por último, los tipos de datos son las descripciones de los recursos intercambiados a través de la API.
Para explicar los distintos pasos a seguir en la creación y uso de APIs mediante Talend, se utilizará un ejemplo sobre personas de una organización.
En este videotutorial, podréis ver en funcionamiento todo lo detallado en este post:
2. Instalación del entorno
Es necesario disponer de una cuenta del cloud de Talend para poder acceder a Talend Administration Center y hacer uso de Talend API Designer y Talend API Tester.
También se necesita tener acceso a Talend Studio para desarrollar los jobs de los que dependerá el servicio ofrecido por la API.
3. API Designer (Talend Administration Center)
El primer paso para la creación de una API mediante Talend es iniciar Talend API Designer. API Designer es una web que permite definir visualmente las distintas partes técnicas de la API y cómo debe comportarse (respuestas esperadas, errores, formatos, etc). También permite el mantenimiento de versiones API, para conseguir que las organizaciones se adapten a nuevos cambios de manera rápida y segura.
Se accede a Talend cloud:
https://portal.eu.cloud.talend.com/
Para iniciar Talend API Designer, desde Talend Administration Center, una vez se inicia sesión, se selecciona esta opción.
Se inicia seleccionando el botón New API.
La configuración es la siguiente:
En General, se nombra la versión como API Clientes 1.0.0 y se le da una descripción, después se guarda.
A continuación, se crean dos tipos de datos, con sus respectivos recursos y operaciones.
Botón + -> Section.
Se añaden dos, uno con nombre Objetos y otro Operaciones.
Ahora, botón + -> Data Type.
Se añaden un tipo de dato (Persona) con la siguiente configuración.
Se añade un atributo a Persona de tipo Objeto (+Add property).
Se genera el tipo de dato a partir de un fichero JSON de ejemplo. Para ello se selecciona Generate from JSON example y se introduce el siguiente código JSON.
{
"ID": "1",
"NOMBRE": "Lucas",
"APELLIDO": "De las Heras",
"EMAIL": "lucas@stratebi.com",
"CIUDAD": "Madrid"
}
Se comprueba que todos los atributos son correctos para el tipo Persona. Se guarda y se valida que en la sección Objetos aparece el nuevo tipo de datos Persona.
Se procede de manera similar con un nuevo tipo de datos Personas del tipo Array.
El siguiente paso es crear un tipo de dato Error del tipo Objeto. Se añaden las siguientes propiedades:
Se vuelve a validar que aparecen los dos nuevos objetos correctamente.
Una vez se crean los recursos es turno de crear las operaciones correspondientes. En este caso se crean tres: Obtener todas las personas, Añadir una nueva persona y Eliminar una persona. Cada operación se añade en Operations -> + > Operation y se configuran como sigue.
Por otro lado, se procede a añadir información extra a la API. Se selecciona y se configura:
Una vez se crea, se valida.
El siguiente objetivo es publicar la documentación de la API creada para que otros miembros de la organización puedan acceder a ella.
Se puede previsualizar la documentación de la API desde Live documentation Preview.
Para publicar la información validada anteriormente, desde Settings -> Live documentation -> Enabled -> ON. La URL se establece como Prueba y del tipo Public.
Ahora el botón Live Documentation Preview es Live Documentation y permite acceder a la documentación de la API.
Para exportar la API una vez se ha terminado de desarrollar, desde el botón Export (al lado del Live Documentation) se descarga un OAS/Swagger a un fichero.
4. Talend Studio
El próximo paso consiste en el uso de las distintas funcionalidades y componentes de Talend Studio para poder interactuar con la API.
Talend Studio es una herramienta de diseño robusta que permite desarrollar en tiempo real distintas funcionalidades y fases de un ciclo de datos. Mediante el uso de Talend Studio se pueden utilizar distintos componentes que permiten el acceso a distintos orígenes de datos, como bases de datos, fuentes de Big Data, así como aplicaciones on-premise y cloud. Además de poder transformar datos, de manera sencilla se pueden crear servicios y rutas que permiten interactuar con las distintas APIs Talend.
El paso inicial con Talend Studio es la creación de un nuevo proyecto de nombre API.
Ahora es necesario iniciar sesión con el usuario de Talend Cloud. Desde Ventana -> Preferencias -> Talend -> Talend Cloud. Otra alternativa es el inicio de sesión mediante token de acceso, desde Talend Cloud -> Preferencias de perfil -> Tokens de acceso personal -> Agregar token.
Desde el Repositoriode Talend Studio, en la sección de Metadata, se añade una nueva REST API Definition.
También en la sección de Metadata, se añade una nueva Db Connection. Se utilizará para conectarse a una tabla personasde una base de datos con datos sobre personas.
Después botón derecho sobre Entrenamientoy Extraer esquemas. De manera automática se consigue extraer el esquema de la tabla personas.
Se prosigue con la creación de una estructura Mediante Talend Data Mapper en Talend Studio, Ventana -> Perspectiva -> Mapping.
Se crea una nueva estructura. Seleccionando la primera opción de importación y después REST API Definition para seleccionar la API de Personas creada anteriormente.
Una vez se crea la estructura está disponible en Data Mapper.
El próximo paso en el desarrollo de una API con Talend es la creación de un servicio REST cambiando a la perspectiva Integration.
Se crea un nuevo Estándar Job de nombre REST_Services. En este job se arrastra desde Metadata -> REST API Definitions la API_Personas.
El componente se configura como sigue.
Se añade un tFlowTolterate y se une por la primera Fila -> Lista_completa_de_personas. A su vez, se rrastra desde Metadata -> Db Connections -> Entrenamiento -> Table schemas -> personas hasta el lienzo. Se selecciona la creación de un nuevo tDBInput. Se une el flujo del tFlowTolterate a “personas”. De la misma manera, se une este flujo a un tHMap y se une a un componente tRESTResponse (su Return Body Type -> String).
El tHMap se configura todo por defecto y se selecciona el schema Personas.
En la nueva ventana emergente se arrastras row (0:*) hasta Persona (0:*).
Se guarda el job y se ejecuta.
Accediendo a http://127.0.0.1:8090/services/personas se obtiene un json con los datos de todas las personas de la base de datos (no es necesario especificar el verbo GET ya que por defecto el navegador lanza esta operación).
El mensaje al parar el servicio es el siguiente.
Se procede a implementar dos operaciones nuevas para la API, POST y DELETE. La operación POST en el REST Service se utilizaría para añadir una nueva persona a la base de datos. La operación DELETE eliminaría una persona determinada de la base de datos.
Para realizar una operación POST, Se crea un Metadata -> File Json de nombre personas donde se importa un json que contiene distintos registros de personas.
Se configura como sigue y se selecciona Refresh Prview.
En el siguiente paso se selecciona el ID como String y se verifica que el metadato json está disponible.
Ahora se amplía el job anterior encargado de realizar el get de personas.
En el componente tRestRequest, se seleccionan los tres puntos situados al lado de Crear_una_persona y se añade una columna body.
Se procede añadiendo un componente tExtractJSONFieldsy se une al rRestRequest mediante la fila Crear_una_persona. Se configura como sigue.
Se continua arrastrando desde Metadata -> Db Connection -> Table schemas -> personas al lienzo e importándolo como un tDBOutput. Se une el componente anterior a este.
También se añade un tWriteJSONFile y un tRestResponse que se unen al flujo.
El último componente se configura a continuación.
El tWriteJSONField tiene la siguiente configuración. Para ello se modifica el nombre del XML tree a body y se arrastran todos los elementos del schema hasta aquí. A continuación, con botón derecho se selecciona el ID como loop element.
Importante deseleccionar la opción avanzada Extend Insert en el segundo tDBOutput.
Para almacenar los registros rechazados se añade un nuevo tWriteJSONField con flujo inicial (rejects) en el segundo tDBOutput y un nuevo tRESTResponse.
La otra operación REST para la API diseñada es un DELETE. Para ello se continúa ampliando el anterior job, añadiento un tMapunido al rRESTRequest mediante Borrar_una_persona.
Además, se arrastra desde Metadata -> Db Connection -> Table schemas -> personas al lienzo y se importa como un tDBOutput.
El tDBOutput se selecciona con la acción Borrar.
Y el tMap se configura a continuación.
Se añade un nuevo tRESTResponse y se une después al tDBOutput (no se acepta la propagación de cambios).
Una vez realizados los pasos anteriores, se consigue crear un job capaz de realizar las operaciones GET, CREATE y DELETE realizadas desde la API creada con la base de datos.
5. API Tester (Talend Administration Center)
Talend API Tester es una aplicación que permite crear distintos escenarios de prueba para simular casos reales de uso de las APIs y sus funcionalidades.
De manera visual se pueden realizar distintos test preconfigurados para la API que indicarán casos de éxito o error, para poder validar la API adecuadamente.
Para conocer el funcionamiento de Talend API Tester, se necesita iniciar el job creado anteriormente en Talend Studio.
Ahora se necesita acceder desde API Designer a API Tester. La primer aves se pide descargar una extensión de navegador.
Ahora se elimina las secciones Sobre y Objetos.
Primero se prueba la operación Crear una persona. Se actualiza el endpoint a http://127.0.0.1:8090/services/personas y Send.
Se puede observar que se realiza correctamente la creación de la nueva persona con ID=25.
Para probar la operación Borrar una persona, se selecciona esta operación y se añade como URL http://127.0.0.1:8090/services/personas/{id}.
Para eliminar un usuario se cambia el id de la URL.
Si se comprueba en la base de datos, este usuario habría sido eliminado.
Por último, la operación GET se prueba de manera similar a las anteriores.
Gracias a API Tester de una manera muy sencilla se pueden comprobar todas las operaciones de la API desarrollada. Sin embargo, también cuenta con una funcionalidad conocida como Escenarios. Gracias a esta funcionalidad, se pueden organizar una serie de peticiones ordenadas para simular casos reales de llamada a la API.
Desde Talend API Tester -> Scenarios. Se selecciona + Add a scenario.
Se le da un nombre y se añaden peticiones existentes. En orden se seleccionan las peticiones a la API ya creadas.
Una vez se crea, se configura la primera solicitud del escenario.
Se selecciona el botón Play que aparece para ejecutar la primera llamada a la API.
El tick confirma cada solicitud validada. Se ejecutan el resto.
De esta manera se pueden similar distintos casos de uso o escenarios donde probar las distintas funcionalidades de la API.
También se puede validar las solicitudes HTTP a través de a afirmaciones/assertions.
Se selecciona la operación Lista completa de personas y en la parte de abajo +Add assertion.
Si se modifica el código esperado a 200 el resultado aparece en verde.
Se añade una nueva que compruebe que el ID de la persona existe.
Ahora se ejecuta el escenario.
Y se comprueba que las afirmaciones añadidas se tienen en cuenta al ejecutar el escenario.
Además, los API Test de Talend permiten el trabajo de integración continúa siguiendo el siguiente “ciclo”.
El siguiente apartado consiste en utilizar el job creado para registros sobre un fichero Excel todas las inserciones y eliminaciones que se realizan sobre la base de datos mediante la API.
Se modifica el job creado anteriormente añadiendo un flujo OnSubjobOk desde el TRESTRequest de la API hasta un tDBInput nuevo configurado en función de una nueva tabla que almacena los cambios conocida como personas_trigger. Finalmente, mediante componente Excel se escriben los datos de cada persona creada o eliminada de la base de datos original de la API.
Las configuraciones de los componentes son.
Antes de lanzar el servicio para realizar llamadas mediante la API, se deben de definir en la base de datos que se está utilizando, dos nuevos trigger.
El primero escribe en la nueva tabla personas_trigger todas las nuevas personas que se crean.
CREATE DEFINER=`sample_user`@`%` TRIGGERafter_personas_insert
AFTER INSERT
ONSampleData.personas FOR EACH ROW
BEGIN
INSERT INTO personas_trigger (ID, NOMBRE, APELLIDO, EMAIL, CIUDAD, REGISTRO)
VALUES(New.ID, New.NOMBRE, New.APELLIDO, New.EMAIL, New.CIUDAD, 'Persona añadida');
END
El siguiente trigger, registra en la nueva tabla las personas eliminadas.
CREATE DEFINER=`sample_user`@`%` TRIGGERbefore_personas_delete
BEFORE DELETE
ONSampleData.personas FOR EACH ROW
BEGIN
INSERT INTO personas_trigger (ID, NOMBRE, APELLIDO, EMAIL, CIUDAD, REGISTRO)
VALUES(Old.ID, Old.NOMBRE, Old.APELLIDO, Old.EMAIL, Old.CIUDAD, 'Persona eliminada');
END
Una vez se definen los triggers, el siguiente paso es ejecutar el job para simular el servicio de la API y probar mediante Talend API Tester, que las operaciones realizadas sobre la base de datos quedan registradas.
Se va a crear una nueva persona de Id 25 desde Talend API Tester, el estado actual de la base de datos de la API personas y personas_trigger es el siguiente.
Se crea una nueva persona.
Sin embargo, al revisar la base de datos se observa que la ciudad de la persona no se ha introducido correctamente. Se procede entonces a eliminar la nueva persona y crearla de nuevo con la ciudad correcta.
El número de filas de la tabla que almacena las operaciones es 3 puesto que se han realizado tres operaciones. Se comprueba que todo está correcto tanto en la base de datos personas como en el documento de registro de operaciones personas_trigger.xls.
6. Versioning & API Portal
Para utilizar API Portal de Talend, se necesita que usuario que se utiliza para las gestiones Cloud, tenga el rol de API Portal – Create and Edit (Publisher) y una cuenta en GitHub. Se accede desde API Designer.
Se selecciona un repositorio privado para la API.
Después se importa la documentación de la Api desarrollada.
Ahora se puede visualizar los últimos cambios realizados sobre la API.
Desde GitHb también se puede ahora descargar el código de la API y su documentación.
Por otro lado, se recomienda que las actualizaciones sobre las funcionalidades de la API o sus nuevas versiones, sigan el patrón Major, minor & patch.
· MAJOR cuando se realizan cambios incompatibles con la anterior versión de la API.
· MINOR cuando se añaden una funcionalidad nueva a la API y sigue siendo compatible.
· PATCH cuando se solucionan pequeños errores de una determinada versión de la API.
Las versiones se representan como 1.4.2 donde 1 indica la versión Major, 4 la versión Minor y 2 el Patch. En este ejemplo, la API estaría es su primera versión Major, donde se han añadido 4 nuevas funcionalidades respecto a la primera versión de la API y se han corregido 2 bugs.
Para desarrollar nuevas versiones, simplemente desde Talend API Designer, se seleccionan los tres puntos y Crear nueva versión, a partir de la versión que se desee avanzar.
7. Buenas prácticas
· Una de las prácticas mas recomendadas en el cliclo de desarrollo de una API mediante el uso de Talend, es la presentación o la creación de los escenarios de pruebas o test, antes de desarrollar y construir los servicios de la API.
Saber mas:
Emilio
Emilio
Emilio
Emilio
Emilio
Emilio
Emilio
Admin
Admin
Admin
Admin
