Saltar al contenido

Tutorial de API REST

Harmony se puede utilizar para consumir cualquier servicio web RESTful, también conocido como API REST. Como las APIs REST están basadas en HTTP, puede conectarse a ellas mediante una Fuente HTTP o Destino HTTP en Harmony Design Studio. Las APIs REST no deben confundirse con los servicios web que utilizan una API SOAP, para lo cual se utiliza un método de servicio web de 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 para 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 objetivo de 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 el resumen de los pasos a continuación para detectar 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 APIs REST pero menos experimentados con Harmony.

Esquema del Tutorial

Estos temas se tratan en este tutorial, presentados en el orden en que deben completarse:

  1. Investigando una API REST
    Hay algunos elementos específicos que debe buscar en la documentación de una API que necesitará más adelante para validar la API y proporcionarlos en la configuración en Design Studio. Estos incluyen configurar el tipo de autenticación que desea que Harmony utilice para autenticarse con la API y obtener URLs de solicitud, encabezados de solicitud, estructuras de solicitud y estructuras de respuesta esperadas.

  2. Validación de una API REST
    Antes de conectarse a una API REST con Harmony, se recomienda encarecidamente realizar pruebas y validación utilizando una herramienta independiente. Esta página explica cómo probar la autenticación y validar y guardar estructuras para cada solicitud y respuesta.

  3. Conexión a una API REST
    En Design Studio, se debe configurar un origen o 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 opciones de configuración comunes, las páginas Fuente HTTP y Destino HTTP proporcionan información más detallada sobre todas las opciones que están disponibles para configurar.

  4. Uso de 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ífica depende 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 métodos en los que necesita proporcionar solo una estructura de respuesta y ninguna estructura de solicitud. Este suele ser el caso con los métodos GET, ya que normalmente solo solicita que se envíen datos desde la API, en lugar de proporcionar datos a la API. Todavía 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 del origen HTTP.

    • Estructuras de solicitud y respuesta
      Este patrón se aplica a métodos en los que se proporcionan estructuras de solicitud y respuesta. Este suele ser el caso con los métodos POST, en los que solicita que se creen datos y luego recibe información sobre lo que se creó. La respuesta de la API se puede utilizar de cualquier forma, pero a menudo se utiliza el nuevo ID de objeto en una operación posterior.

    • Solo una estructura de solicitud
      Este patrón se aplica a los métodos en los que proporciona una estructura de solicitud, pero la API REST no devuelve datos estructurados. Para 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 solicitud ni 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 generalmente se especifica completamente con la URL y los encabezados de la solicitud; la respuesta es normalmente un código de estado.

Recursos Adicionales