Conéctese a una API REST

Introducción

Esta página muestra cómo utilizar la información obtenida al validar una API REST para conectarse a la API en Harmony. Esta página continúa el Tutorial de API REST utilizando API REST de Atlassian Jira Cloud v2 como ejemplo, utilizando la información que se recopiló después de Investigar una API REST y validado en Validación de una API REST.

La conexión a la API dentro de Harmony se configura a través de Design Studio. A diferencia de los servicios web basados en WSDL, no hay disponible un asistente que guíe la configuración. En su lugar, una conexión a una API REST se configura configurando un origen HTTP o un destino HTTP. Posteriormente utilizará el origen o el destino HTTP en una operación como se describe en Uso de una API REST en operaciones.

Si bien este tutorial se centra únicamente en las opciones de configuración comunes, se recomienda a los usuarios experimentados e inexpertos que revisen las páginas Fuente HTTP y Destino HTTP, que proporcionan información más detallada sobre todas las opciones que están disponibles para configurar.

Configurar un Origen o Destino HTTP

A continuación se proporciona un ejemplo de configuración utilizando el ejemplo de Jira, seguido de subsecciones que describen partes particulares de la configuración de origen/destino HTTP. Consulte la documentación para Fuente HTTP y Destino HTTP para saber cómo crear un origen o un destino, así como todas las opciones configurables disponibles.

Verbo HTTP y URL

Durante la configuración, seleccione el Verbo HTTP apropiado para su solicitud y proporcione la misma URL que utilizó como URL de solicitud en Postman.

Para hacer que la URL sea dinámica, puede usar proyecto o variables globales en lugar de una URL base o para agregar parámetros de consultar.

Si se utilizan variables, también puede proporcionar valores predeterminados (como se muestran entre llaves) para fines de prueba o predeterminados. (Si no se proporcionan los valores predeterminados, la prueba de la conexión puede fallar, pero debido a que los valores de las variables se completarán en tiempo de ejecución, la operación aún debería tener éxito en tiempo de ejecución).

Por ejemplo, para nuestro PUT "Editar problema" de Jira, nuestra URL se construye como:

https://[jira.baseUrl{my-domain.atlassian.net}]/rest/api/2/issue/[jira.issueKey{TEST-11}]

Autenticación

La configuración de autenticación variará según los diferentes métodos de autenticación.

En el ejemplo, debido a que usamos autenticación básica, completamos el mismo Inicio de sesión y Contraseña que usamos para las pruebas (también empleando variables de proyecto), y luego expandió Opciones para seleccionar la casilla de verificación Usar autenticación HTTP básica.

Debe utilizar el tipo de autenticación que haya configurado para su extremo específico. Por ejemplo, si estuviera utilizando autenticación negociada, como con un servidor Windows que tiene autenticación integrada, deberá completar Inicio de sesión y Contraseña pero no seleccionar la casilla de verificación para autenticación básica.

Como otro ejemplo, si estuviera usando autenticación basada en token, podría dejar estas credenciales en blanco y en su lugar proporcionar un proyecto o variable global token de autenticación en los encabezados de solicitud en Opciones > Propiedades avanzadas. Una configuración típica basada en token se describe en Transformación REST - Sugar CRM - Solicitar token de sesión.

Encabezados

En Propiedades avanzadas también es donde debe proporcionar cualquier encabezado de solicitud adicional que aún no esté cubierto en la interfaz HTTP de origen/destino. Para cada llamada, se recomienda verificar los encabezados de solicitud al validar la API para asegurarse de tener todos los encabezados de solicitud requeridos.

Al proporcionar encabezados de solicitud con el cuadro Propiedades avanzadas "Encabezados de solicitud (una línea por encabezado)", tenga en cuenta que la ayuda de autocompletado estándar para variables en Design Studio no funciona en esta área. Es decir, cuando comienzas a escribir un corchete abierto ([), no se le presentarán opciones de variables existentes. Sin embargo, es útil saber que aún puedes usar proyecto o variables globales en esta área.

Los encabezados de respuesta, por otro lado, no se validan en Harmony. Sin embargo, si necesita utilizar algo proporcionado en el encabezado de respuesta de la API, puede utilizar la variable Jitterbit apropiada para un origen o destino HTTP:

• Fuente HTTP: $jitterbit.source.http.response.header.*

• Destino HTTP: $jitterbit.target.http.response.header.*

La documentación para estas variables se proporciona en Variables de Jitterbit de origen y Variables de Jitterbit objetivo.

Tipo de Contenido

Para destinos HTTP, en Opciones, verifique que el tipo de contenido coincida con el formato esperado por la API. Tenga en cuenta que esta opción se aplica únicamente al formato de la estructura de solicitud (no a la estructura de respuesta).

Es típico que las APIs REST acepten solicitudes y proporcionen respuestas en JSON, como es el caso de nuestro ejemplo de API Jira. En este ejemplo, borramos la casilla de verificación para un tipo de contenido predeterminado de text/plain e ingresé un tipo de contenido personalizado de application/json.

Si proporciona una solicitud de API REST en un formato diferente, especifique el tipo de contenido en consecuencia. Si el método no acepta datos estructurados, desmarque la casilla y deje este campo en blanco.

Respuesta

Para un destino HTTP que utiliza una solicitud que proporciona una respuesta que le gustaría escribir en otro destino, configure esto en Opciones.

Aquí se puede utilizar cualquier tipo de objetivo. En nuestro ejemplo de la POST "Crear problema" de Jira, elegimos escribir la respuesta en un objetivo de variable global utilizando una variable global llamada "Respuesta". Para conjuntos de datos de más de 4 MB, se recomienda utilizar almacenamiento temporal en lugar de utilizar una variable global (consulte Variable global frente a almacenamiento temporal).

Conexión de Prueba

Una vez que haya completado la configuración, haga clic en Probar conexión para verificar que Harmony pueda conectarse a su API REST.

Para una fuente HTTP, si tiene éxito, debería recibir de vuelta el archivo con el nombre de la URL. Tenga en cuenta que no puede leer el contenido del archivo desde aquí; probar la conexión solo verifica que estás recibiendo algo de la API. Más tarde, después de usar la fuente en una operación, puede usar el contenido si lo desea.

Para un destino HTTP, si tiene éxito, el mensaje simplemente indicará que la conexión se realizó correctamente.

Si la conexión falla al utilizar la misma URL de solicitud y método de autenticación que probó exitosamente en Postman, entonces el problema probablemente esté relacionado con la configuración del origen o destino HTTP en Design Studio. Vuelva a consultar la documentación sobre Fuente HTTP y Destino HTTP y verifique su configuración.

Próximos Pasos

Después de haber configurado un origen o destino HTTP, el siguiente paso es Usar una API REST en Operaciones. Aunque cada API REST cumple con las mismas restricciones arquitectónicas, no todas están diseñadas de la misma manera para cada método HTTP. Como cada solicitud y respuesta específicas dependen de la API específica, en el siguiente paso presentamos cuatro patrones de diseño para diseñar operaciones.