Antes de adentrarnos en el mundo de Swagger, repasemos brevemente qué es una API y para qué sirve.
¿Qué es una API?
El término 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. Por ejemplo, cuando una app nos permite iniciar sesión con Facebook o Google, se está conectando a la API de esas empresas para obtener nuestros datos de sesión.
Las APIs pueden ser privadas, abiertas solo para partners, o públicas. También es 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 una tienda virtual con web y app móvil:
- Versión web de la tienda (responsive)
- Versión mobile
- Base de datos para los productos
- Módulo de pago
Cuando un usuario compra 2 de 10 teléfonos desde la web, el stock baja a 8, y desde la app deberíamos ver 8 y no 10. Esa conexión se logra con APIs: ambas plataformas consumen el mismo backend (API local). Y para el módulo de pago podemos usar APIs existentes de MercadoPago, PayPal o similares sin desarrollar nada de cero (API externa).
¿Qué son los endpoints y los métodos?
Los endpoints son las URLs de una API, y cada uno puede tener varios métodos: las formas de interactuar con él.
- 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.
¿Qué es Swagger?
Hoy no existe una única forma estandarizada de escribir una API: cada programador puede hacerla a su gusto. Pero ¿qué pasa cuando llega otro programador que quiere usarla, o un QA que quiere testearla?
Ahí entra Swagger. Nace para resolver ese problema: su objetivo es estandarizar el vocabulario que usan las APIs, como una especie de diccionario. Cuando hablamos de Swagger nos referimos a una serie de reglas, especificaciones y herramientas que ayudan a documentar APIs de una forma que todo el mundo entienda.
Existen varias plataformas que hacen lo mismo, pero Swagger es la más conocida y tiene una buena interfaz, Swagger UI, que no solo muestra endpoints y métodos sino que permite probarlos. Basta de teoría, ¡a testear!
Para este taller uso una URL que suelo llevar a mis capacitaciones: petstore.swagger.io, un ejemplo de tienda de mascotas con varios endpoints y métodos para practicar.
En la parte superior de Swagger UI encontramos la URL base, importante si después queremos usar estos mismos métodos en Postman. Lo otro a mirar es el botón Authorize. En esta Petstore no hace falta autenticación, pero en muchos casos sí.
Si sos QA y necesitás autenticarte, lo recomendable es hablar con el desarrollador para que te indique cómo, ya que no hay una sola forma correcta de hacer una API: la autenticación puede ser con usuario y contraseña, token, etc.
Lo siguiente son todos los endpoints del sistema y los métodos de cada uno: qué podemos hacer con cada endpoint.
Por último están los modelos, que indican qué estructura y qué tipo de datos debe tener cada JSON.
Antes de arrancar, una aclaración: para usar los métodos desde Swagger UI hay que hacer clic en Try it out; de lo contrario, los campos aparecen bloqueados.
POST (crear nueva mascota)
Para enviar un POST sí o sí debemos ver cómo está hecho el modelo, porque necesitamos respetar la misma estructura y los tipos de dato (string, integer, boolean…). Con el JSON completo, hacemos clic en el botón azul Execute.
Lo que hacemos es enviar un request con la información que deseamos enviar o solicitar, y recibimos un response del servidor.
En este caso devuelve un 200, el response de una consulta efectuada correctamente, y creó una nueva mascota llamada “Titan”.
GET (traer todas las mascotas o una por ID)
Podemos traer todas las mascotas filtradas por estado, o una sola por ID.
Primero traemos todas: seleccionamos un estado y hacemos clic en Execute.
Trajo todos los animales con ese estado (si el listado es largo puede demorar). Ahora traemos una sola: vamos al GET que filtra por petId y colocamos el ID de alguna mascota.
PUT (modificar una mascota existente)
Entramos al método PUT, enviamos el nuevo JSON con los datos modificados y hacemos clic en Execute. Hay que enviar el ID de la mascota que queremos modificar para que los cambios se apliquen a esa mascota en específico.
DELETE (eliminar una mascota por ID)
Solo especificamos el petId de la mascota que queremos eliminar y hacemos clic en Execute.
El PATCH no lo puedo mostrar porque este ejemplo no lo trae, pero el mecanismo es exactamente el mismo.
Tené en cuenta que no siempre va a ser igual al ejemplo: como no hay una sola forma de crear APIs, pueden variar campos, modelos, métodos y demás. Pero la mecánica para testearlas siempre es la misma.