Investigue una API REST

Introducción

Esta página está destinada a aquellos que no están familiarizados con el proceso de recopilación de información sobre una API específica y cubre los aspectos específicos que se deben buscar en la documentación de una API que son relevantes para configurar una integración en Harmony.

Si no está familiarizado con una API específica, lo primero que debe hacer es localizar su documentación. Algunas API tienen múltiples versiones o productos, así que preste atención a la versión específica. Cada vez es más común que la documentación de la API se incruste en la implementación de la API. Dichas API se pueden documentar utilizando la especificación OpenAPI/Swagger u otros marcos. Otra documentación de API que no está incrustada puede ser más susceptible a imprecisiones, lo que hace que las pruebas y la validación sean aún más importantes.

A los efectos de este tutorial, utilizamos Atlassian Jira Cloud REST API v2 como ejemplo.

Autenticación

Dentro de la documentación de la API, busque instrucciones sobre cómo configurar el tipo de autenticación que desea que Harmony use para autenticarse con la API, como básica, OAuth o basada en token. Luego configure la autenticación deseada según sea necesario.

Usando el ejemplo de Jira, configuramos la autenticación básica siguiendo la documentación de Jira en Autenticación básica para API REST. Con este tipo de autenticación, podremos configurar Harmony para usar un nombre de usuario y una contraseña para autenticarnos con Jira.

Más adelante en este tutorial, le mostraremos cómo puede probar esta configuración (consulte Validación de una API REST) y cómo utilizar cualquier método de autenticación que haya configurado para configurar un origen o destino HTTP en Design Studio (consulte Conexión a una API REST).

URL de Solicitud

Para cada llamada a la API, deberá conocer la URL asociada. La documentación debe mostrar cómo construir esta URL, que a menudo es una combinación de una URL base para el extremo específico junto con parámetros para la solicitud específica. La URL puede incluir parámetros que están destinados a ser reemplazados por los identificadores de registro específicos con los que desea interactuar.

En la documentación de la API, se puede enumerar la URL o la URL parcial para cada tipo de solicitud, o se puede mostrar dentro de una solicitud completa. La documentación de Jira proporciona ambos. Por ejemplo, la ruta URL parcial se proporciona para "Crear problema":

POST /rest/api/2/issue

La documentación de Jira también proporciona ejemplos para cada solicitud de una variedad de herramientas y lenguajes (como cURL, Node.js, Java, Python y PHP). La URL completa completa con un nombre de dominio ficticio que deberá reemplazarse se puede encontrar dentro de cada ejemplo. La solicitud cURL de ejemplo proporciona la URL después de --url opción:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue'

La documentación de una API debe tener en cuenta los parámetros de consultar que se pueden agregar al final de la URL. Más adelante, en Design Studio, podrá hacer que la URL base y cualquier parámetro de consultar sean dinámicos reemplazándolos con variables globales o de proyecto en la URL proporcionada en la configuración de origen o destino de HTTP. Un ejemplo de esto se proporciona más adelante en este tutorial en Conexión a una API REST.

Encabezados de Solicitud

Para cada llamada a una API REST, tome nota de los encabezados incluidos en la solicitud.

En Design Studio, la información de encabezado que se incluye con mayor frecuencia se especifica durante la configuración estándar de un origen o destino HTTP, como la autenticación y el tipo de contenido. Tomar nota de los valores necesarios le ayuda a configurar correctamente el origen o el destino. Se pueden especificar encabezados de solicitud adicionales al configurar el origen/destino en Opciones > Propiedades avanzadas (y se trata en Conexión a una API REST).

En la solicitud cURL de ejemplo, la información del encabezado se proporciona como --header opciones:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

Estructuras de Solicitud y Respuesta

Para cada llamada a una API REST, deberá conocer las estructuras de solicitud y respuesta, si están presentes.

No todas las llamadas a la API tienen una estructura de solicitud o respuesta. Si una llamada usa una (o ambas) de estas estructuras depende de la API específica. Las API bien documentadas suelen proporcionar la estructura de la solicitud. Se puede proporcionar la estructura de respuesta, pero en cualquier caso se puede obtener utilizando una herramienta como Postman o SoapUI.

Para las llamadas que aceptan datos de solicitud estructurados, la estructura debe proporcionarse en la documentación, ya sea incluida en la solicitud o proporcionada por separado. Las solicitudes codificadas pueden ser para una variedad de herramientas o idiomas, con la carga útil en un formato esperado por la API, por lo que debe estar familiarizado con la herramienta o el idioma que se utiliza para saber dónde buscar la estructura de la solicitud.

Por ejemplo, en la documentación de la API de Jira para "Crear problema", la estructura de la solicitud se encuentra dentro de la --data opción para cURL (como se ve a continuación) y se proporciona en varios otros idiomas. Es posible que deba ajustar los datos de entrada para la solicitud específica, por ejemplo, reemplazando los valores de cualquier campo (como la clave del proyecto de Jira y el tipo de problema) con aquellos que son válidos para el extremo específico. Luego deberá proporcionar esta estructura de entrada al validar la llamada en una herramienta como Postman, como se explica más adelante en Validación de una API REST.

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"fields": {"project": {"key": "TEST"}, "summary": "REST ye merry gentlemen.", "description": "Creating of an issue using project keys and issue type names using the REST API", "issuetype": {"name": "Bug"}}}'

Some API calls do not contain any structured input data for the request. For example, in the case of Jira's "Get Issue," the absence of --datos containing a structure indicates this call does not accept structured request data, as is common for GET calls.

curl --solicitud OBTENER \
  --url ' https:// <su-dominio>.atlassian.net/rest/api/2/issue/<issueIdOrKey>' \
  -- encabezado 'Autorización: Portador <token_de_acceso>' \
  -- encabezado 'Aceptar: aplicación/json'

Using a GET can be helpful in cases where the API documentation may not have an accurate or complete request structure, or in cases where you have added custom fields. You can perform a GET on an existing object to obtain a list of possible fields or values, then use that structure later in Postman to test what might be accepted for the request in another method.

For calls that return structured response data from the API, if the documentation provides a sample response, note what format it is in and familiarize yourself with what is returned. Most REST APIs provide responses in JSON, but some APIs may provide XML or another type. For now, you don't need to copy the response provided by the documentation; we will generate the actual response from the API later for use in Design Studio (see Validating a REST API).

Take note of any documented status codes that are expected to be returned. These will be useful as reference to interpret the response received from the API after making the request. For example, the following table shows codes that can be returned from the Jira "Create Issue" request. In addition to a status code, error messages with helpful information may be returned in a structured response.

Jira "Get Issue" Status Codes

Otra Información Exclusiva del Extremo

La importancia general de familiarizarse con su extremo no se puede enfatizar lo suficiente. La documentación de una API puede proporcionar recomendaciones o precauciones para ayudarlo en el camino. Por ejemplo, en la documentación de Jira, hay notas especiales sobre permisos, expansión de recursos, paginación y encabezados especiales. Estar al tanto de lo que está disponible (o no disponible) lo ayudará a diseñar integraciones exitosas y abordar cualquier desafío que encuentre.

Próximos Pasos

Una vez que haya configurado la autenticación deseada y se haya familiarizado con la documentación de la API, consulte estas páginas para conocer los siguientes pasos:

• Validación de una API REST
  Antes de conectarse a una API REST con Harmony, se recomienda realizar pruebas y validaciones con una herramienta independiente. Esta página lo guía a través de la prueba de autenticación y la validación y el almacenamiento de estructuras para cada solicitud y respuesta.

• Conectándose a una API REST
  En Design Studio, se debe configurar un origen 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 Destino HTTP proporcionan información más detallada sobre todas las opciones que están disponibles para configurar.

• Usando 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ífica depende de la API específica, presentamos cuatro patrones de diseño para diseñar operaciones.