Documenta tu API con Postman.

Postman es una excelente herramienta, te permite como desarrollador probar cada uno de los endpoints de tu API, de esa manera puedes verlos funcionar sin la necesidad de un cliente.

Pero Postman ofrece muchos más servicios, uno de ellos es la documentación de tu API.

Partamos del hecho de que el desarrollo de software es un trabajo 100% colaborativo, sin embargo, no todo es código, existen muchas maneras de colaborar y a aportar a una aplicación. Otro desarrollador que quiera consumir tu API para un cliente no va a tomarse el tiempo de leer tu código para saber a que endpoints debe apuntarle y cuales son los parámetros que debe enviar. Sencillamente si no tiene una documentación no va a utilizarla.

A medida que vamos desarrollando tareas para agregarle valor a nuestra aplicación tenemos que sacar tiempo no sólo para desarrollar sino también para otras tareas, cómo hacer pruebas unitarias, verificar que nuestros servicios puedan ser llamados y añadir estos nuevos servicios a la documentación.

Y ahí está el valor de Postman, entre otras cosas, permitiéndonos ahorra tiempo y ser más ágiles con nuestras entregas.

Muy bien, empecemos, para éste tutorial vamos a necesitar la aplicación de escritorio de Postman, la puedes descargar acá, también vamos a necesitar una cuenta en Postman.

Lo primero que vamos a hacer es crear un workspace para nuestro equipo, de esta manera vamos a poder colaborar con la prueba y documentación de estos endpoints.

Para esto vamos a seleccionar la pestaña de workspaces de postman, al lado del botón de invite y le vamos a dar donde dice teams.

Luego de esto vamos a seleccionar create new y nos debe salir esta pantalla.

Vamos a llenar los campos y crearemos nuestro workspace del equipo de trabajo.

Luego de eso ya tendremos el workspace de nuestro equipo y podremos añadirle nuestra colección con sus servicios y peticiones.

Vamos a crear una nueva colección haciendo click en el botón de Create a collection y llenamos los siguientes datos. En mi caso quedará algo así.

Podemos añadir más opciones, como pasarle parámetros de autorización, de esta manera cada una de las peticiones que generemos tendrá estos parámetros.

En este caso no lo voy a llenar.

Le damos crear y ya tenemos nuestra colección.

Ahora vamos a crear nuestro primer servicio, para ello vamos a hacer click en el botón de tres puntos de la colección y le vamos a dar click en Add Folder.

Le agregamos la información a la carpeta, las descripciones en Postman soportan Markdown, esto es muy valioso a la hora de añadirle cierto formato a nuestra descripción.

Muy bien, le damos crear y si expandimos nuestra colección ahí tenemos nuestro servicio de cursos.

Ahora vamos a crear nuestra petición de cursos, un getAll.

Para ello desplegamos nuestra carpeta o servicio, le damos click en Add requests y llenamos la información.

Nuevamente hacemos uso de markdown para entregar la descripción en un mejor formato y le damos save.

Ahora con nuestra petición creada sólo debemos hacer doble click en ella para abrirla en una de las pestañas de Postman y llenamos toda la información necesaria para correrla.

Un paréntesis, dependiendo del entorno en el que nos encontremos probando, ya sea desarrollo, staging, o producción vamos a tener diferentes variables, una de ellas es la URL a la cual se debe apuntar.

Entonces creemos un entorno de desarrollo con su respectiva URL.

Para ello vamos a hacer click en el botón de settings (la tuerca) que se encuentra cerca de donde dice No Environment. Esto nos va a desplegar nuestro menú de entornos de Postman.

Y le damos click en add.

Esto nos va a desplegar un menú donde podremos añadir nuestro entorno y las variables que posee.

He añadido la URL y una variable que no vamos a utilizar llamada secret_key, la razón es diferenciar las columnas INITIAL VALUE y CURRENT VALUE.

Los entornos y sus variables suben a la documentación, de esta manera la persona que va a correr nuestra aplicación sabrá, por ejemplo a que URL debe apuntar dependiendo del entorno en el que se encuentre. Pero a veces tenemos información sensible que no queremos que suba, como una llave para conectarnos a un servicio externo. Esas variables las llenamos en la columna CURRENT VALUE para poderlas utilizar localmente pero no las llenamos en la columna de INITIAL VALUE, de esta manera, la variable va a subir, informando a quien lea la documentación que es necesaria, sin embargo, su valor no va a subir a la documentación y no existirá el riesgo de que sea expuesta.

Vamos a hacer click en el botón de add para añadir nuestro entorno con sus variables.

Ya tenemos nuestro entorno de desarrollo en Postman.

Vamos a cerrar el menú de entornos y luego lo vamos a seleccionar en donde dice No Environment.

Debe quedar de la siguiente manera.

Muy bien, ya teniendo nuestro entorno preparado, vamos llenar los campos para hacer nuestra petición.

Añadí un parámetro de query opcional, sólo para mostrar en nuestra petición cómo quedarían documentados esos campos en caso de tenerlos.

Ya teniendo preparada nuestra petición vamos a hacer click en send para ver la respuesta que recibimos de nuestra API.

Postman nos muestra nuesta respuesta y también nos da una opción muy valiosa para salvarla debajo del botón de send, save response. Y nos permite salvar la respuesta como ejemplo o como archivo, seleccionaremos como ejemplo.

Esto nos va mostrar la pestaña de nuestro ejemplo, y nos va a permitir colocarle el nombre que deseemos, en este caso yo lo nombré como success. También si tenemos otros formatos de respuestas esperados podríamos añadirlos a nuestros ejemplos, por ejemplo, unauthorized podría ser un caso y ejemplificar el formato de la respuesta que se recibiría en ese caso.

Vamos a hacer click en save example y ya tendríamos todo listo para ir a nuestra documentación.

Para ello vamos a colocar el cursor encima de nuestra colección y veremos que encima del botón de los tres puntos está uno con un triángulo. Vamos a hacer click ahí. Nos debe mostrar el siguiente menú.

Luego de eso vamos a hacer click en View in web y se va a desplegar una pestaña de nuestro navegador con la documentación.

A mano izquierda vamos a ver las secciones de nuestra API, en nuestro caso la introducción y el servicio de cursos.

En el medio veremos arriba una pequeña sección de configuración donde podremos elegir el entorno en el que vamos a estar trabajando, el layout y las peticiones.

Y en la parte derecha están los ejemplos y una configuración para seleccionar el lenguaje con el que queremos trabajar las peticiones.

En este caso vamos seleccionar JavaScript - Fetch. Y también en entornos voy a seleccionar Development.

En la imagen superior se alcanza a ver la ruta de la petición que hicimos, y en ella, donde debería estar nuestra URL se muestra la variable {{url}}, esto es porque no hemos seleccionado ningún entorno. Una vez lo seleccionemos la variable se va a popular.

Si no ves el entorno en creamos a la primera, simplemente recarga la página y debería aparecer.

Ahora bien, si hacemos scroll hacia abajo vamos a ver con más detalle la petición que documentamos.

Por un lado tenemos la petición con su respectiva descripción, gracias a Markdown pudimos darle un mejor formato, también tenemos nuestro parámetro de prueba con una descripción donde se especifica si es opcional o requerido.

Y por otro lado tenemos un ejemplo de como hacer la petición utilizando fetch y un ejemplo de la respuesta que esperamos recibir.

Si situamos el cursor sobre uno de estos dos ejemplos podremos expandir estas ventanas.

Petición

Respuesta

Ambas nos dicen a que ejemplo pertenecen.

¡Ahora podemos agilizar el tiempo de documentación de nuestra API y hacer entregas más rápidas para nuestra aplicación gracias a Postman!