Tutorial de API REST
Harmony se puede utilizar para consumir cualquier servicio web RESTful, también conocido como API REST. Como las APIs REST se basan en HTTP, te conectas a ellas mediante una fuente HTTP o objetivo HTTP en Jitterbit Design Studio. Las APIs REST no deben confundirse con los servicios web que utilizan una API SOAP, para los cuales se utiliza un método de servicio web Harmony se utiliza en su lugar.
Este tutorial muestra un ejemplo completo de cómo consumir APIs REST en Harmony usando Atlassian Jira como extremo con fines de demostración. El mismo proceso se puede aplicar a cualquier extremo que utilice una API REST. Algunos otros ejemplos de APIs REST incluyen Magento, ServiceNow, Shopify, DocuSign, SharePoint, Epicor, Zendesk, Zoho y Sugar CRM, por nombrar algunos.
El público al que va dirigido este tutorial es alguien que no esté familiarizado con las APIs REST y sus pruebas, y que tenga conocimientos básicos de Harmony. Si, en cambio, tiene más experiencia con uno o todos estos temas, le recomendamos que lea rápidamente el esquema de pasos a continuación para encontrar cualquier punto de interés. El último tema, Uso de una API REST en operaciones, puede ser de mayor interés para aquellos con experiencia con las APIs REST pero menos experiencia con Harmony.
Esquema del tutorial
Este tutorial cubre estos temas y los presenta en el orden en que deben completarse:
-
Investigación de una API REST
Hay algunos elementos específicos que debes buscar en la documentación de una API que necesitarás más adelante para validar la API y proporcionar en la configuración en Design Studio. Estos incluyen configurar el tipo de autenticación que quieres que Harmony use para autenticarse con la API y obtener las URLs de solicitud, los encabezados de solicitud, las estructuras de solicitud y las estructuras de respuesta esperadas. -
Validación de una API REST
Antes de conectarse a una API REST con Harmony, se recomienda encarecidamente realizar pruebas y validaciones con una herramienta independiente. En esta página, se explica cómo probar la autenticación y validar y guardar las estructuras para cada solicitud y respuesta. -
Conexión a una API REST
En Design Studio, se debe configurar una fuente o un destino HTTP para el método HTTP apropiado de su solicitud (GET, PUT, POST, DELETE o método personalizado) para que pueda usarlo en una operación. Si bien esta página se centra en las opciones de configuración comunes, las páginas Fuente HTTP y objetivo HTTP proporciona información más detallada sobre todas las opciones que están disponibles para configurar. -
Uso de una API REST en operaciones
Aunque cada API REST se adhiere a 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, presentamos cuatro patrones de diseño para diseñar operaciones:-
Solo una estructura de respuesta
Este patrón se aplica a los métodos en los que solo necesitas proporcionar una estructura de respuesta y ninguna estructura de solicitud. Este suele ser el caso con los métodos GET, ya que normalmente solo estás solicitando que se envíen datos desde la API, en lugar de proporcionar datos a la API. Aún estás enviando una solicitud a la API, pero tu solicitud no está en forma de datos estructurados. La solicitud se realiza simplemente utilizando la URL de solicitud y cualquier encabezado de solicitud u otras opciones configurables establecidas durante la configuración de la fuente HTTP. -
Estructuras de solicitud y respuesta
Este patrón se aplica a los métodos en los que se proporcionan estructuras de solicitud y respuesta. Este suele ser el caso de los métodos POST, en los que se solicita la creación de datos y luego se recibe información sobre lo que se creó. La respuesta de la API se puede utilizar de cualquier forma, pero a menudo se utilizan los nuevos identificadores de objeto en una operación posterior. -
Solo una estructura de solicitud
Este patrón se aplica a los métodos en los que se proporciona una estructura de solicitud, pero la API REST no devuelve datos estructurados. En el caso de las APIs que solo tienen una estructura de solicitud, esto no significa que la API no responda; significa que la respuesta de la API puede ser tan simple como un código de estado. -
Ni una petición ni una respuesta
Este patrón se aplica a métodos que no aceptan datos de entrada estructurados ni devuelven datos de salida estructurados. En tales casos, la solicitud suele especificarse en su totalidad con la URL y los encabezados de solicitud; la respuesta normalmente es un código de estado.
-