En el tutorial anterior vimos cómo testear APIs con Swagger. En esta ocasión vamos a realizar los mismos ejercicios, pero utilizando Postman. Antes de empezar repaso la misma introducción del post anterior para refrescar la teoría sobre APIs (si ya la leíste, podés saltar directo a la parte de Postman).
¿Qué es una API?
API es la abreviatura de Application Programming Interface, interfaz de programación de aplicaciones. De forma resumida, se utiliza para permitir la comunicación entre dos aplicaciones a través de un conjunto de reglas.
En esa comunicación establecemos cómo un módulo de un software interactúa con otro, para cumplir una o muchas funciones según los permisos que el propietario de la API le dé a los desarrolladores de terceros.
De cara al usuario final, lo único que se ve de una API son los resultados. Un ejemplo: cuando una aplicación móvil o web nos permite iniciar sesión con nuestra cuenta de Facebook o Google, esa aplicación se está conectando a la API de esas empresas para obtener nuestros datos de sesión.
Las APIs pueden ser privadas para uso de una empresa, abiertas solo para partners, o públicas para que cualquier desarrollador interactúe con ellas. También es muy común ver APIs locales para que las aplicaciones se comuniquen dentro de un mismo ambiente.
¿Para qué sirve una API?
Una de sus funciones principales es facilitar el trabajo de los desarrolladores y ahorrar tiempo y dinero. Supongamos que nos piden desarrollar una tienda virtual con web y aplicación móvil. Tendría una estructura como esta:
- Versión web de la tienda (para acceder desde la PC o el móvil de forma responsive)
- Versión mobile (para instalar en el móvil)
- Base de datos para almacenar los productos
- Módulo de pago
Cuando un usuario entra a la web y de 10 teléfonos compra 2, el sistema debería descontarlos del stock y quedarían 8. Si entramos desde la app móvil y revisamos ese producto, deberíamos ver 8 y no 10.
Toda esa conexión se logra a través de APIs: ambas plataformas consumen el mismo backend y el desarrollador no tiene que escribir un código para la web y otro para la versión móvil (este es un ejemplo de API local).
Por otro lado, para el módulo de pago podemos usar APIs existentes de pasarelas como MercadoPago o PayPal, sin desarrollar nada de cero (este es un ejemplo de API externa, porque interactuamos con una API que no creamos nosotros).
¿Qué son los endpoints y los métodos?
Los endpoints son las URLs de una API, y cada endpoint puede tener varios métodos: las formas que tenemos de interactuar con él. Los más comunes:
- POST
- Crear un recurso nuevo.
- PUT
- Modificar un recurso existente.
- GET
- Consultar información de un recurso.
- DELETE
- Eliminar un recurso determinado.
- PATCH
- Modificar solamente un atributo de un recurso.
Con el ejemplo de la tienda: con POST creamos un producto, con PUT lo modificamos, con GET traemos todos los productos o uno en específico, con DELETE lo eliminamos y con PATCH modificamos un atributo.
¿Qué es Postman?
Postman es un cliente que permite gestionar peticiones a las APIs. Es una herramienta muy completa y muy utilizada, y su mayor ventaja es que permite crear tests automatizados. Además, hoy existe versión web y versión de escritorio con colecciones sincronizadas, y podemos compartir nuestras colecciones con el equipo, lo que la vuelve nuestra nueva mejor amiga.
Para empezar, descargamos Postman desde postman.com/downloads. Abrimos el programa y vamos a Workspaces → New Workspace.
Le ponemos un nombre y lo creamos. Acá podemos invitar a compañeros para que vean y colaboren en el espacio de trabajo.
Una vez creado, debemos crear una colección: básicamente, el conjunto de peticiones que tendrá un endpoint. Usaré la misma API del post anterior: petstore.swagger.io.
Esta colección servirá para testear los métodos principales del endpoint pet.
Con la colección creada, agregamos requests: uno por cada método que queramos testear. El primero será el GET para listar todas las mascotas según su estado. Vamos al Swagger y vemos a qué URL hay que hacer el request.
Ejemplo método GET (listar)
Esa misma URL es la que ponemos en el GET de Postman.
Al hacer clic en Send vemos los resultados que devuelve la petición.
Una aclaración: para este GET debemos especificar sí o sí el estado (disponibles, vendidas o pendientes). Swagger nos deja seleccionarlo desde la interfaz web, pero en Postman debemos pasarlo como parámetro. Esto lo pone automáticamente en la URL; y si lo colocamos en la URL, se agrega automáticamente como parámetro.
Ejemplo método POST (crear)
Para agregar un nuevo request vamos a los tres puntos de la colección y hacemos clic en Add Request.
Para el método POST debemos enviar un body tal cual indica la documentación de Swagger.
Copiamos ese body y lo pegamos en el body de Postman. Hay que seleccionar la opción raw e indicar que es de tipo JSON.
Al hacer clic en Send, nos devuelve una respuesta con status 200, lo que indica que se creó correctamente.
Ejemplo método PUT (actualizar)
Muy similar al anterior: colocamos en el body el JSON con las modificaciones. Para este método es fundamental especificar el ID de la mascota, para que la API sepa cuál modificar.
Al hacer clic en Send se envía la petición y se aplica el cambio. En este caso actualicé el nombre de la mascota que creamos antes.
Ejemplo método DELETE (eliminar)
Con este último método eliminamos una mascota. Para ello colocamos el ID en la URL del request.
Al presionar Send, se elimina la mascota con ese ID.