Orígenes de datos desde servicios web REST/json

Orígenes de datos desde servicios web REST/json

Resumen

El conector a servicios web REST/JSON ofrece todas las capacidades necesarias para conectarse a este tipo de orígenes. Esta opción permite recolectar datos desde servicios web  REST/JSON o configurar acciones de escritura, para luego crear vistas de datos y exponerlos en métodos de tu API.

Para conectarse a un servicio web, debes ir a Orígenes de Datos → Desde servicio web → REST/JSON


Conceptos básicos

El término REST (Representational state transfer o Transferencia de estado representacional) representa una definición de diseño de arquitectura software que cuando cumple todas sus especificaciones es llamado RESTful.

El término JSON hace rerferecia al formato de solicitud y respuesta que entregará el servicio

URL o endpoint

Toda solicitud HTTP requiere de una URI que se relaciona a un recurso o entidad. La forma más conocida de las URIs son las URLs, que se componen de la siguiente sintaxis:


Segmento
 Descripción
Protocolo
En este caso el protocolo es HTTP o HTTPS. Ej.: https://

Dominio
El nombre de dominio indica la dirección del servicio. Ej.: api.example.com. De forma alternativa, puede suceder que en lugar de un dominio se utilice una dirección IP.

Puerto
El puerto indica la puerta por la que se accederá al servicio. En los casos HTTP se utiliza por defecto el puerto 80, y cuando es HTTPS el puerto 443. No es necesario especificar el puerto en las conexiones a los servicios, a menos que el servicio indiquen un puerto especifico o diferente al standar.
Ruta de acceso
La ruta, o path, define la ruta de acceso al recurso del servicio. Ej.: /accounts/v1/invoices

Parámetros
En el contexto de una URI por parámetros se entiende a los query-params, que son enviados luego del símbolo "?". Los parámetros son una lista de pares de llave-valor separados por el símbolo "&". Ej.: ?accountId=99&year=2022&status=3

En base a lo detallado y al ejemplo indicado, la URI completa del servicio es:


Métodos de petición o solicitud

Los servicios web REST/JSON utilizan el protocolo HTTP para realizar las transferencias, por tanto hacen uso de sus métodos de petición o solicitud.

Los métodos de solicitud indican el tipo de acción que se realizará sobre un recurso determinado. Así, pueden pensarse como verbos: consultar, crear, modificar, eliminar, etc.

Los métodos más utilizados en las solicitudes de servicios web REST/JSON son los siguientes:

Tipo de solicitud
 Descripción
GET
El método GET se utiliza para consultar u obtener datos del origen.

POST

 El método POST se utiliza normalmente para enviar un recurso o entidad al origen, es decir, para crear un nuevo registro.
A pesar de ello, pueden existir métodos POST que no realicen cambios en el origen sino que se utilicen para obtener datos.
PUT
El método PUT se utiliza para realizar el cambio de la totalidad de una entidad en el origen.

PATCH
El método PATCH se utiliza para aplicar modificaciones parciales en una entidad en el origen.

DELETE
El método DELETE se utiliza para borrar o eliminar una entidad o recurso en el origen.


Si bien esa es la definición del estándar, el servicio web puede no ajustarse a estas especificaciones. Por ello, debe tomar se como referencia y conocer cuál es el tipo de solicitud que espera su servicio web.


Cabeceras de la solicitud

Las cabeceras (o headers) HTTP permiten enviar información adicional en la solicitud y recibir información adicional en la respuesta. Las cabeceras se componen de un nombre y valor.

Cuerpo de la solicitud

El cuerpo de la solicitud (o body) es información que se envía al origen al realizar la consulta.

El cuerpo de la solicitud tiene una relación directa con la cabecera Content-Type que indica el tipo de contenido que es enviado en la solicitud.

Esquemas de autenticación y autorización

Un servicio web REST/JSON puede requerir algun tipo específico de autenticación y/o autorización, o ninguno.

Éstos pueden clasificarse en:
Sin autorización
Autorización básica (Basic Auth)
Bearer token


Tipo de autorización
 Descripción
Sin autorización
El método no requiere ningun tipo de autenticación y autorización.

Basic Auth
La autorización básica consiste en un usuario y contraseña que será enviado en la solicitud al servicio encodeado en base64.


Authorization, API Key,  Token u otros





Una forma común en proteger los servicios web es mediante una autorización mediante una llave. Esta llave puede asumir el nombre de Token, API Key u otros.

La llave suele enviarse en la cabecera Authorization y puede ser precedida de un prefijo.

Por ejemplo, el caso más extentido es utilizando la cabecera mencionada: Authorization: Bearer XYZXYZ.



Security Token Service (STS), OAuth20 o autenticación en dos pasos
Un servicio puede estar protegido bajo un esquema de STS, OAuth20 o una autenticación es dos pasos. Esto significa que antes de ejecutar la consulta al servicio, debe ejecutarse otro método para obtener un token y posteriormente utilizar ese token para consultar el servicio. Es en ese sentido una autenticación en dos pasos.




Configurar un servicio REST/JSON

Los conceptos básicos descriptos anteriormente tuvieron por objetivo comprender qué puede requerirse para configurar un servicio REST/JSON en la plataforma.

Ahora, se explicará cómo configurar este tipo de servicios en Workspace.

La configuración puede dividirse en la solicitud que se realizará al servicio y en el procesamiento de su respuesta.

Solicitud

Para configurar la solicitud al servicio deberá considerar los siguientes aspectos. Una vez realizada la configuración, deberá hacer clic sobre el botón Probar para realizar la solicitud.



Método de la solicitud

Deberá indicar el método o tipo de solicitud: GET, POST, PUT, PATCH o DELETE.



Endpoint o URL

Deberá ingresar el endpoint o URI.

En caso que lo requiera podrá mapear segmentos del endpoint para luego exponerlo como parámetros del método o relacionarlos a variables de contexto.

La funcionalidad de Agregar mapeo permite configurar segmentos de la URL como parámetros. Por ejemplo, la ruta de nuestro origen es https://api.vor-tex.io/accounts/v1/users/{{userId}} , donde "{{userId}}" representa una variable que debemos exponer como parámetro de un método para que su valor pueda ser modificado en la solicitud.



Debe hacer clic sobre el botón Agregar mapeo e ingresar un Nombre de mapeo que será el nombre del parámetro y un valor por defecto. Luego haga clic sobre Confirmar.



Se mostrarán los Mapeos disponibles y en la URL del Origen, deberá agregar el nombre del mapeo entre llaves dobles en la posición que corresponda. En este caso, {{userId}} es el nombre del mapeo.

Al crear la vista de datos visualizará el parámetro "userId" y podrá agregar las validaciones si corresponde.

Puede agregar múltiples mapeos sobre una ruta de Origen.

Autorización

En caso que sel servicio requiera algún tipo de Autorización deberá configurarla.

Puede configurar:
  1. Basic Authorization
  2. Bearer Token
  3. Security Token Service (STS)



Basic Auth

Puede autenticarse meditante Basic Auth, donde se utiliza un usuario y contraseña. La plataforma se ocupará de generar el valor de 'usuario: contraseña' codificado en base64 para enviarlo como corresponde en este tipo de autententicación: Authorization: Basic Zm9vOmJhcg==



Bearer Token

En caso que el servicio esté protegido por un access token sin vencimiento y deba enviarse el prefijo Bearer debe utilizar esta opción.



Security Token Service (STS)

Esta modalidad de autenticación consiste en realizar una solicitud previa a la solicitud a los datos para obtener un token. Es el tipo de autenticación del estándar OAuth20, aunque la plataforma es flexible para servicios que no se ajusten a dicho estándar.

Una vez seleccionada la opción, deberá hacer clic en Configurar.

Se mostrará esta pantalla donde podrá configurar la solicitud de obtención del token y el procesamiento de su respuesta.

Deberá indicar de forma obligatoria la ruta al token mediante un JsonPath, y en caso que se encuentre informado en la respuesta la ruta al tiempo de expiración del token.


Podrá definir el tipo de contenido de la solcitud, esto es, el Content-Type.


Y podrá agregar los parámetros que sean requeridos en la solicitud.



Al Guardar la configuración volverá a la pantalla inicial de configuración de solicitud al servicio.

Por defecto, el token obtenido se enviará en la cabera Authorization con el prefijo Bearer y el valor del token. Puede modificar el valor del prefijo en caso que sea necesario.




Cabeceras

En caso que el servicio requiera el envío de cabeceras específicas en la solicitud deberá configurarlas.



Las cabeceras pueden ser no editables (por defecto), editables o aplicar mapeos sobre un segmento de su valor. En el caso de ser editables o agregar mapeos, podrá exponerlas como parámetros o cabeceras del método de su API y asignarlas a variables de contexto.



Cuerpo de la solicitud

El cuerpo de la solicitud es parte del contenido que será enviado en la solicitud y tiene una estrecha relación con el tipo de contenido o Content-Type.

Podrá seleccionar entre los diferentes tipos de contenido y luego agregar parámetros.



application/json

Por ejemplo, en el siguiente caso representado en cURL es un método POST que requiere el envío de un body-json:
curl --location --request POST 'https://miservidor.com/api/metodo'  \ --header  'Content-Type: application/json'  \ --data-raw  '{      "accountId": 99,      "date" :  "2022-08-01" }'
Para configurar este servicio web como origen de datos, deberemos seleccionar el tipo de solicitud POST y el Content-Type application/json. Esto habilitará la opción para ingresar el body o cuerpo de la solicitud.

Si se requiere que los valores de los atributos del cuerpo de la solicitud sean parámetros editables en la vista de datos y método de la API, debemos utilizar la funcionalidad de Agregar mapeos.

Debe hacer clic sobre el botón Agregar mapeo e ingresar un Nombre de mapeo que será el nombre del parámetro y un valor por defecto. Luego haga clic sobre Agregar.

Se mostrarán los Mapeos disponibles y en el json de la solicitud, deberá agregar el nombre del mapeo entre llaves dobles en la posición que corresponda.




El nombre del mapeo será el nombre de los parámetros de la vista de datos y de los métodos de las APIs. Los nombres de los parámetros pueden ser iguales o diferentes a los atributos del json de la solicitud. Esto le permite modificar los nombres de sus parámetros con mayor flexibilidad.

application/x-www-form-urlencoded y multipart/form-data

Si selecciona estas opciones de tipo de contenido, luego deberá agregar los parámetros en la pestaña Parámetros.

Parámetros

Los parámetros de la solicitud son parte del contenido que será enviado en la solicitud al servicio y están relacionados el tipo de contenido o cuerpo de la solicitud configurado.

Si no selecciona un tipo de contenido, los parámetros agregados serán enviados en la query-string, esto es, bajo la forma api.example.com/method/?key=value

Los parámetros de consulta se pueden definir como los pares clave-valor opcionales que aparecen después del signo de interrogación en la URL. Básicamente, son extensiones de la URL que se utilizan en la ejecució del servicio web.

Los parámetros de consulta se añaden al final de la URL con un "?". El signo de interrogación se utiliza para separar la ruta y los parámetros de consulta.

Puede representarse de la siguiente manera: https://myserver.com/resource-name?param1=value1&param2=value2


En ese caso, deberá ingresar en Nombre "anio" y en valor "1999", y hacer lo mismo para el caso de "mes". Si selecciona la opción "El valor será editable" esté se mostrará como valor editable en la vista de datos y en los métodos de su API. De esa manera, al ser editable, el usuario final podrá modificar esos valores.

No ingrese parámetros editables que contengan tokens o claves de acceso al servicio web.

Acciones de lectura o escritura

Independientemente del tipo de solicitud que se realice al servicio web, puede definir el tipo de acción que está realizando. Esto le permite evitar ejecuciones de escritura indeseadas al origen. Por defecto, estará seleccionada la opción de Lectura. Solo en caso que esté realizando acciones de escritura deberá seleccionar esa opción.

Respuesta

Una vez realizadas las configuraciones de la solicitud y habiendo obtenido la respuesta mediante el botón Probar, podrá comenzar a trabajar el en el procesamiento de la respuesta.

El objetivo de las siguientes configuraciones en procesar la respuesta para obtener los datos requeridos en un formato tabular, para luego aplicar transformaciones y enriquecimiento en la vista de datos. De todas formas, siempre podrá exponer si lo desea la respuesta tal como fue recibida desde el servicio, sin aplicar transformaciones (vea formatos de métodos).¿Qué es el JsonPath?

Ruta a los datos (o path to data)

¿Qué es el JsonPath?

El JsonPath utiliza una anotación especial para representar nodos y sus conexiones a nodos adyacentes en una ruta JsonPath.

El JsonPath utiliza una anotación especial para representar nodos y sus conexiones a nodos adyacentes en una ruta JsonPath.  El signo "$" representa el objeto raíz.

Así se vería una anotación típica:
$.result
Puedes usar e sta herramienta para evaluar tu JsonPath si tienes dudas.

En síntesis, el JsonPath le permite definir qué elemento del la respuesta Json del servicio web se tabulará en la vista de datos.

Por ejemplo, si la respuesta de su servicio web es la siguiente, su JsonPath será $.result 
{ "meta": { "status": "ok", "lenght": 6 }, "result": [ { "account": { "base_uri": "https://vor-tex.io", "is_active": true, "account_id": 33, "account_name": "Vor-Tex" }, "surname": "Doe", "name": "John", "created": "2020-04-10T11:22:54.332"
 ...


Puedes Previsualizar la respueta con el botón debajo:



Ahora, como se observa, al celdas que contienen objetos JSON, dado que la estructura de la respuesta contiene anidados. Puedes dejarlo de esa forma, o puedes extraer los datos de los objetos mediante la evaluación de ruta a los datos.



Evaluar ruta a los datos

Deberás ingresar los nodos a los que se quiere acceder. Los mismos deberán estar separados por | (pipe/barra lateral) y en el caso de acceder a los hijos de un nodo, se deberá usar . (punto).

Por ejemplo,  utilizando el ejemplo de respuesta anterior puedes seleccionar cada atributo.



La previsualización tabulada se verá así:



Identificación de títulos/cabeceras

Los servicios web suelen informar los títulos, cabeceras o atributos de los datos. Esta configuración le permitirá definir las cabeceras de su vista de datos.

En los ejemplos anteriores, el título de los valores se encuentra informado como atributos. En ese caso, debe seleccionar "Sí, son los atributos"


En el caso de que estén en una ruta diferente a la de los datos, se deberá configurar la ruta a las cabeceras siguiendo el criterio del JsonPath explicado anteriormente.

Si su servicio web no tiene títulos/cabeceras de los valores, no se preocupe, podrá agregar cabeceras en la vista de datos.

Validación de respuesta

Es una configuración opcional que le permite ingresar  una validación adicional para saber si la respuesta entregada es realmente la esperada, dado que puede venir informado en alguno de sus atributos que no fue asi.



Campos extendidos

Los campos extendidos se utilizan para extraer datos por fuera de la tabla de datos y cabeceras. Para cada campo debe ingresar nombre, descripción y ruta.

Siguiento el ejemplo de respuesta anterior, la ruta para obtener el valor del atributo "lenght" será "$.meta.lenght".




Definir metadatos

Una vez que se haya configurado su servicio web, deberá hacer clic en Continuar y completar los metadatos que le permitirán encontrar posteriormente su origen de datos y mantener sus recursos ordenados.

El origen de Datos se crea por defecto en estado de Borrador.

Frecuencia de actualización

En el segundo paso, al completar los metadatos, podrá definir la frecuencia de actualización se sus datos.

Este es el primer nivel de gestión de caché de la plataforma. Sugerimos seleccionar la opción que se corresponda con la frecuencia de actualización de los datos en el origen.



Por ejemplo, si los datos se actualizan cada una hora, seleccione la opción "Cada hora". Si son datos de actualización diaria, por ejemplo indicadores financieros, seleccione la opción "Diaria"

Con la opción "Otro" puede ingresar un cron específico.

Si no sabe qué opción seleccionar, no seleccione ninguna o seleccione "Bajo demanda".

Hasta aquí a configurado su origen de datos desde servicio web. Ahora deberá crear una vista de datos para continuar con el proceso.

    • Related Articles

    • Orígenes de datos desde Bases de datos

      Resumen El conector a Bases de datos ofrece todas las capacidades necesarias para conectarse a este tipo de orígenes. Esta opción permite recolectar datos desde diferentes tipos de bases de datos o configurar acciones de escritura, para luego crear ...

    • Orígenes de datos desde URLs

      Resumen El conector de URLs permite recolectar datos desde protocolos HTTP(s) y FTP. Para recolectar datos desde un archivo alojado en una URL, debes ir a Orígenes de Datos → Desde URLs Configuración Ingresar una URL con un  enlace válido desde donde ...

    • Qué es una vista de datos

      Resumen La plataforma no requiere de un proceso ETL off-line para extraer los datos desde los orígenes, sino que asociadas a la vista se encuentran un conjunto de reglas que el motor de datos interpreta para consultar la fuente a demanda o ...

    • Orígenes de datos desde servicios web SOAP/xml

      Resumen El conector a servicios web SOAP/xml ofrece todas las capacidades necesarias para conectarse a este tipo de orígenes. Esta opción permite recolectar datos desde servicios web  SOAP/xml o configurar acciones de escritura, para luego crear ...

    • Qué son los orígenes de datos

      Resumen Los orígenes de datos son el punto de partida del flujo de los datos, a partir de los cuales se crearán vistas de datos y métodos de APIs. A continuación se detallan las caraceterísticas de los orígenes de datos. Algunos conceptos básicos ...