¿Qué son y porqué utilizar los documentos descargables de una API?

Cuando ingresas a la documentación de un producto y luego a la de una API, vas a encontrar tres (3) descargables en nuestro ambiente sandbox, los cuales al descargar sabemos que te servirán como mapa de ruta en el entendimiento y exploración de las capacidades funcionales que te exponemos en nuestras APIs.

Colecciones de pruebas

Es la agrupación de peticiones que no solo brinda un conjunto de casos de prueba, sino que permite la creación de un flujo de trabajo en una estructura organizada y sencilla.

Con este tendrás la descripción detallada de las acciones, condiciones y entradas necesarias para evaluar un aspecto particular y así puedas examinar y verificar las capacidades que expone la API.

Al descargar la colección de pruebas, podrás utilizar esa estructura ya organizada en la herramienta que prefieras, en el artículo ¿Cómo probar las APIs en Insomnia? detallamos cómo utilizarlas.

Escenarios de prueba

Un escenario de pruebas proporciona un guion o historia y muestra cómo se espera que la API funcione en condiciones generales y amplias; busca dar una visión panorámica, simular situaciones de uso real y facilitar la comprensión del comportamiento de una capacidad.

Los escenarios de prueba están construidos bajo un lenguaje Gherkin, un estándar basado en lenguaje natural con una estructura de palabras clave.

• Escenario
• Dado
• Cuando
• Entonces

Firma o contrato de la API

La firma o también conocida como contrato de una API,  es la documentación completa del comportamiento, la funcionalidad y el protocolo de comunicación que te ofrece la API. En esta detallamos los métodos API proporcionados, los formatos y estructuras de datos admitidos, las entradas esperadas, las posibles respuestas, los códigos de error y otras instrucciones esenciales para su consumo.

Este contrato nos brinda beneficios en la comprensión de la API,  nos ayuda a garantizar coherencia en el uso de API y, al adherirte a él, no solo te va a facilitar las pruebas, sino que podemos garantizar la integración e interoperabilidad en los componentes de software.