Validar una API REST

Introducción

En esta página, mostramos cómo utilizar una herramienta independiente para validar las estructuras de solicitud y respuesta de una API REST. Esta página continúa el Tutorial de API REST utilizando API REST de Atlassian Jira Cloud v2 como ejemplo, continuando desde el paso anterior de Investigar una API REST. Este tutorial está destinado a un usuario sin experiencia que no está familiarizado con las pruebas y validación de API.

Antes de conectarse a una API REST con Harmony, se recomienda encarecidamente probar y validar utilizando una herramienta independiente por varias razones:

Solución de problemas enfocada: La mayoría de los problemas con las APIs REST en Harmony son el resultado de no haber construido la solicitud como se requiere para recuperar la respuesta deseada de la API. Realizar esta solución de problemas utilizando una herramienta independiente garantiza que las solicitudes específicas sean válidas antes de introducir la automatización.
Iteración rápida: Al diseñar una integración, es posible que no conozca todos los campos o valores que desea, o que no pueda realizar solicitudes válidas en el primer intento. Realizar pruebas rápidas que obtengan comentarios inmediatos puede ayudarle a crear las solicitudes para su caso de uso específico de manera eficiente, permitiéndole modificar su solicitud hasta que se genere la respuesta que desea.
Estructuras reales: La documentación API para las estructuras de solicitud y respuesta de muestra puede estar desactualizada, no tener en cuenta una configuración específica de su extremo, estar incompleta o ser inexacta de alguna otra manera. Según la experiencia, recomendamos encarecidamente utilizar las respuestas de datos estructurados reales de la propia API para que Harmony sepa cómo procesar sus datos correctamente.

Hay una variedad de herramientas disponibles para validar las APIs REST. En este tutorial, utilizamos el Cartero debido a su simplicidad, pero puedes usar cualquier herramienta de tu preferencia, como SoapUI. Si está disponible, también puede utilizar el portal desarrollador de un proveedor de API o la funcionalidad de prueba OpenAPI/Swagger, siempre que se proporcionen las estructuras de solicitud y respuesta.

Autenticación de Prueba

El primer paso de la prueba es asegurarse de que puede conectarse correctamente a la API REST utilizando el tipo de autenticación configurado.

En la documentación de la API, busque una URL de solicitud para probar que proporcione una respuesta. Usar un GET para probar la autenticación suele ser la forma más sencilla de asegurarse de que puede conectarse. Otros métodos en los que se transfieren datos al extremo pueden requerir permisos que luego puede identificar y solucionar problemas más adelante, una vez que sepa que la pieza de autenticación está funcionando.

Primero, cree la URL de solicitud y reemplace la URL base con la de su extremo específico, según corresponda. Por ahora, no se preocupe por proporcionar los detalles específicos de la solicitud; sólo queremos asegurarnos de que podemos establecer una conexión. Usando "Obtener metadatos de creación de problemas" de Jira como ejemplo, encontramos en la documentación que la URL de solicitud se construye usando https://<your-domain>.atlassian.net/rest/api/2/issue/createmeta. En Postman, dado que el método es GET, utilizamos el menú desplegable para seleccionar OBTENER e ingresamos la URL de solicitud para nuestro extremo.

A continuación, proporcione los detalles de autenticación para su extremo. En Postman, esto se hace en la sección Autorización. Como usamos autenticación básica, seleccionamos Autenticación básica e ingresamos las credenciales de Jira que usaremos en Design Studio más adelante. Aunque este ejemplo utiliza autenticación básica, puede utilizar cualquier tipo de autenticación admitido por su extremo.

Detalles de autenticación de Extremo

Con la URL de solicitud y la información de autenticación ingresadas, envíe la solicitud a la API (en Postman, haga clic en Enviar). Si la conexión es exitosa, debería recibir una respuesta de la API, generalmente como una estructura, un código de estado exitoso o ambos, según el método y la API específicos. Si la conexión falla, consulte la documentación de la API y su extremo para detectar errores de configuración.

Advertencia

Si no puede conectarse en Postman o una herramienta similar, no podrá conectarse en Harmony.

Solicitud de autenticación de Extremo

Validar y Guardar Estructuras para Cada Solicitud y Respuesta

Una vez que haya confirmado que puede conectarse a la API REST correctamente, utilice el mismo proceso para (1) validar cada solicitud que desee que Harmony pueda realizar a la API para interactuar con los datos de su punto final y (2) guardar las estructuras de solicitud y respuesta (si están presentes) en archivos separados que luego necesitará en Design Studio.

Para validar cada solicitud en Postman, siga los mismos pasos que antes para proporcionar la URL de la solicitud (para cada llamada) y los detalles de autenticación.

Si una llamada requiere una estructura de solicitud, de la cual debería haber obtenido anteriormente una muestra de la documentación de la API, deberá proporcionarla en Postman. En la sección Cuerpo, seleccione el botón de opción sin formato y use el menú desplegable para configurar el formato apropiado (content-type). En el ejemplo, como ocurre con la mayoría de las APIs REST, el formato es JSON (application/json). Pegue la estructura de la solicitud y realice los ajustes necesarios para que la solicitud sea válida (por ejemplo, cambiar la clave del proyecto Jira y el tipo de problema). Estos ajustes dependerán de su solicitud API real.

Una vez que haya completado la información de la solicitud, haga clic en Enviar. Si es necesario, identificar y solucionar problemas y repita hasta obtener la estructura de respuesta API que desea. Los datos reales incluidos en la respuesta de muestra no son relevantes, ya que la API REST proporcionará los datos reales a Harmony en el momento en que se realiza la solicitud.

Una vez que tenga la estructura de datos para usar en su integración, guarde cada estructura de solicitud y respuesta (si está presente) en sus propios archivos. Asegúrese de guardar en el formato de archivo correcto; la mayoría de las APIs REST proporcionan respuestas en JSON, pero algunas pueden usar XML u otro tipo según la API. Guarde los archivos donde pueda acceder a ellos cuando esté configurando su proyecto en Design Studio.

Tenga en cuenta que si no tiene intención de utilizar todos los campos proporcionados en la respuesta en su integración, esto está perfectamente bien y es lo esperado. Puede simplemente dejarlos ahí o, si lo desea, puede optar por eliminarlos manualmente de la estructura de muestra. Pero debe asegurarse de que todos los campos que planea utilizar estén incluidos; de lo contrario, no podrás utilizarlos en Harmony.

Precaución

Si elimina campos de la estructura de muestra, tenga en cuenta que durante la ejecución Harmony puede informar advertencias de que hay elementos adicionales en su transformación. Estas advertencias se pueden ignorar si los campos se eliminaron intencionalmente.

Para este ejemplo, utilizamos Postman para validar las siguientes estructuras de solicitud y respuesta y luego guardamos estas estructuras en archivos locales. Estos son los archivos que luego necesitaremos proporcionar en Design Studio mientras configuramos la transformación para que Harmony pueda procesar los datos correctamente.

Jira OBTENER "obtener Problema"

En este escenario común, primero usamos un método GET que devuelve campos y valores reales de un objeto existente dentro del extremo. Después de ver cuáles son esos campos y valores, podríamos usarlos más adelante en PUT, POST, DELETE u otro método.

Solicitar URL: OBTENER https://my-domain.atlassian.net/rest/api/2/issue/TEST-10
Estructura de solicitud: Ninguna. La documentación de la API de Jira indica que no hay datos de entrada asociados con la solicitud, lo cual tiene sentido porque el objeto específico que se solicita se proporciona en la URL de la solicitud.

Estructura de respuesta: Editamos la estructura de respuesta para eliminar campos que no queremos usar (un paso opcional) y la guardamos en un archivo local llamado Jira_GET_GetIssue_Response.json:

Jira_GET_GetIssue_Response.json

{
    "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
    "id": "10572",
    "self": "https://my-domain.atlassian.net/rest/api/2/issue/10572",
    "key": "TEST-10",
    "fields": {
        "issuetype": {
            "self": "https://my-domain.atlassian.net/rest/api/2/issuetype/10003",
            "id": "10003",
            "description": "A task that needs to be done.",
            "name": "Task",
            "subtask": false
        },
        "project": {
            "id": "10200",
            "key": "TEST"
        },
        "priority": {
            "self": "https://my-domain.atlassian.net/rest/api/2/priority/3",
            "iconUrl": "https://my-domain.atlassian.net/images/icons/priorities/medium.svg",
            "name": "Medium",
            "id": "3"
        },
        "labels": [],
        "versions": [],
        "status": {
            "name": "To Do"
        },
        "description": "This task is for manually updating JIRA because there is no integration in place.",
        "security": null,
        "summary": "Manual Updates",
        "comment": {
            "comments": [],
            "maxResults": 0,
            "total": 0,
            "startAt": 0
        }
    }
}

Jira POST "crear Problema"

Ahora enviamos una solicitud para crear un nuevo objeto utilizando algunos de los mismos campos devueltos por GET. Para conocer los valores posibles, primero podría llamar a un GET diferente que devuelva la misma estructura.

Solicitar URL: PUBLICAR https://my-domain.atlassian.net/rest/api/2/issue/

Estructura de solicitud: Guardado en un archivo local llamado Jira_POST_CreateIssue_Request.json.

Jira_POST_CreateIssue_Request.json

{
    "fields": {
       "project":
       {
          "key": "TEST"
       },
       "summary": "Jitterbit REST API Integration",
       "description": "Build an integration in Jitterbit so we can automatically sync our systems using our endpoint's REST API.",
       "priority": {
        "name": "Medium"
        },
       "issuetype": {
          "name": "Task"
       }
   }
}

Estructura de respuesta: Guardado en un archivo local llamado Jira_POST_CreateIssue_Response.json. También podemos verificar nuestro extremo para ver que se haya creado el nuevo problema o hacer un GET en el identificador del nuevo objeto.
Jira_POST_CreateIssue_Response.json
```
{
    "id": "10576",
    "key": "TEST-11",
    "self": "https://jitterbitse.atlassian.net/rest/api/2/issue/10576"
}
```

Jira PUT "editar Problema"

A continuación, editamos el problema que acabamos de crear para modificar los valores de algunos de sus campos existentes y agregar otros nuevos.

Solicitar URL: PUT https://my-domain.atlassian.net/rest/api/2/issue/TEST-11

Estructura de solicitud: Guardado en un archivo local llamado Jira_PUT_EditIssue_Request.json.

Jira_PUT_EditIssue_Request.json

{
  "update": {
    "comment": [
      {
        "add": {
          "body": "Ticket updated via REST API."
        }
      }
    ]
  },
  "fields": {
    "priority": {
        "name": "Highest"
    },
    "labels": ["business-priority", "customer-priority"]
    }
}

Estructura de respuesta: Ninguna. En Postman, recibimos un código de estado 204, que según la documentación de la API es la respuesta esperada si el problema se actualizó correctamente. También podemos consultar nuestro extremo en la aplicación web de Jira o realizar otro GET para ver que se han realizado las actualizaciones.

Jira DELETE "eliminar Problema"

Finalmente, eliminamos el objeto que creamos y editamos.

Solicitar URL: BORRAR https://my-domain.atlassian.net/rest/api/2/issue/TEST-11
Estructura de solicitud: Ninguna. El identificador del objeto se proporciona en la URL.
Estructura de respuesta: Ninguna. El código de estado devuelto es 204, que según la documentación de la API de Jira indica que el problema se eliminó correctamente. Esto también se puede verificar en la aplicación web de Jira o confirmar con un GET fallido.

Próximos Pasos

Después de haber validado y guardado la estructura para cada solicitud y respuesta, consulte estas páginas para conocer los siguientes pasos:

Conectando 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.
Usando 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, presentamos cuatro patrones de diseño para diseñar operaciones.