Antes de adentrarnos en el mundo de Swagger, vamos a repasar brevemente lo que es una API y para que sirven.
¿Qué es una API?
El término API es una abreviatura de Application Programming Interfaces, que en español significa interfaz de programación de aplicaciones. De forma resumida podemos decir que se utiliza para permitir la comunicación entre dos aplicaciones a través de un conjunto de reglas.
Es esta comunicación podemos establecer como un módulo de un software interactúa con otro, para cumplir una o muchas funciones dependiendo de los permisos que les dé el propietario de la API a los desarrolladores de terceros.
De cara al usuario final, lo único que se ve de una API, son los resultados. Un ejemplo de esto, es cuando entramos a una aplicación móvil o web y nos permite loguear utilizando nuestra cuenta de Facebook o Google. En este caso, esa aplicación se esta conectando a la API de estas empresas para obtener tus datos de sesión.
Las API pueden ser privadas para el uso de una empresa, abiertas sólo para partners, o públicas para que cualquier desarrollador pueda interactuar con ellas. También es muy común ver APIs locales para que aplicaciones se comuniquen dentro de un mismo ambiente.
¿Para qué sirve una API?
Una de las principales funciones de una API es la de poder facilitarle el trabajo a los desarrolladores y ahorrar tiempo y dinero. Para explicar esto con un ejemplo y que quede claro, vamos a suponer que nos piden desarrollar una tienda virtual que tenga una web y una aplicación móvil. Esta tienda tendría una estructura como la siguiente:
- Versión web de la tienda (para acceder desde la PC o desde el movil 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 página web de la tienda y de 10 teléfonos compra 2, el sistema debería descontarlos del stock y nos quedarían 8 teléfonos. Si entramos desde la aplicación móvil y revisamos ese producto luego de la compra, deberíamos ver 8 productos y no 10.
Toda esta conexión se puede lograr a través de APIs, ahorrandole al desarrollador tener que escribir un código para la web y uno para la versión móvil, debido a que ambas plataformas consumen el mismo backend. (Esto es un ejemplo de una API local)
Por otro lado, en el listado de funcionalidades mencionamos al módulo de pago. En este caso para ahorrarnos tiempos de desarrollo, podemos usar APIs existentes para la pasarela de pago y así permitirle al usuario poder pagar a través deMercadoPago, Paypal o cualquier otra plataforma similar sin tener que desarrollar algo de cero. (Esto es un ejemplo de una API externa, debido a que estamos interactuando con una API no creada por nosotros)
¿Qué son los EndPoint y los métodos?
De forma resumida podemos decir que los EndPoint son las URLs de una API y cada EndPoint puede tener varios métodos. Los métodos son todas las formas que tenemos de poder interactura con ese EndPoint.
Entre los métodos más comunes encontramos a los siguientes:
- 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.
Para explicarlo con el ejemplo de la tienda podemos decir que con el método POST, podemos crear un nuevo producto. Con el método PUT podemos modificar un producto de la tienda, con el GET podemos traer todos los productos o un producto en específico, con el DELETE podemos eliminar el producto y con el PATCH podemos modificar un atributo de un producto.
¿Qué es Swagger?
Actualmente no existe una sola forma estandarizada de escribir una API, es decir, cada programador puede programarla a gusto suyo, debido a que no existe una sola forma de desarrollarlas. Pero que pasa si viene otro programador que quiere utilizarla o un QA que quiera testearla…?
Acá es en donde entra en juego Swagger. Esta potente herramienta nace como intención de solucionar este problema. Su objetivo es estandarizar el vocabulario que usan las APIs. Es una especie de diccionario.
Cuando mencionamos a Swagger, nos referimos a una serie de reglas, especificaciones y herramientas que nos ayudan a documentar nuestras APIs, documentación que todo el mundo pueda entender.
Existen varias plataformas que hacen esto mismo, pero la más conocida es Swagger, tiene una buena interfaz de usuario que se llama Swagger UI, que permite no solo ver los endpoint y métodos, sino que también permite probarlos.
Basta de teoría, ¡empecemos a testear!
Para este tutorial/taller, les traje una URL que suelo usar en mis capacitaciones
Se trata de un ejemplo de un Petstore con varios endpoints y métodos que se pueden usar para practicar.
En la parte superior de Swagger UI vamos a encontrar la URL Base, que es muy importante saberla por si después queremos usar estos mismos métodos en Postman (que lo explicaré en otra guía). Lo otro importante a ver, es el botón de Authorize. En esta web de Petstore no hace falta autenticación, pero en muchos casos, si.
En caso de que sean QA, y necesiten autenticarse, lo recomendable es hablar con el desarrollador para que nos indique de que forma hay que hacerlo, ya que como dije antes, no hay una sola forma correcta de hacer una API, y la autenticación puede ser a traves de un usuario y contraseña, un token, etc.
Lo siguiente que vamos a ver, van a ser todos los endpoint que tiene el sistema y los métodos de cada uno de ellos. Es decir, que cosa podemos hacer con cada uno de esos endpoints.
Por último, vamos a ver los modelos. Estos nos indican que tipo de estructura y que tipo de datos debe tener cada json.
Para este taller, vamos a ver un ejemplo de cada método. Antes de arrancar, quiero hacer una aclaración. Para poder utilizar los métodos desde Swagger UI, debemos clickear el botón Try it out, de lo contrario, los campos aparecerán bloqueados.
POST (Crear nueva mascota)
Para enviar un POST, si o si debemos ver como esta hecho el modelo, debido a que necesitamos respetar la misma estructura.
Recuerden también que debemos respetar el tipo de dato, es decir, si es un string, un integer, boolean, etc.
Una vez que tenemos completo el json, clickeamos en el botón azul «Execute»
Lo que estamos haciendo acá, es enviar un «REQUEST», con la información que deseamos enviar o solicitar. Y recibimos un «RESPONSE» con una respuesta por parte del servidor.
En este caso, devuelve un 200, que es un response de cuando la consulta fue efectuada correctamente. Y acá creó a una nueva mascota llamada «Titan»
GET (Traer todas las mascotas y traer una en específica por ID)
Como podemos ver en la imagen, podemos traer TODAS las mascotas filtrandolas por un estado, o traer una sola en específico por ID.
Vamos a probar primero traer a todas las mascotas. Seleccionamos un estado y damos click en «Execute»
En este caso trajo a TODOS los animales con ese estado (si el listado es largo, puede demorar un poco en traer los resultados).
Ahora vamos a intentar traer a una sola mascota, para ello vamos al GET que filtra por petID y colocamos el ID de alguna mascota.
Como vemos en la imagen, solo trae esa mascota en específico.
PUT (Modificar una mascota existente)
Para poder modificar una mascota, entramos al método PUT y enviamos el nuevo Json con los datos MODIFICADOS y clickeamos en el botón «Execute». Algo que debemos tener en cuenta, es que necesitamos enviar el ID de la mascota que intentamos modificar para que le aplique los cambios a esa mascota en específico.
DELETE (Eliminar una mascota por ID)
Para el caso del DELETE, solo debemos especificar el petID de la mascota que deseamos eliminar y clickeamos en el botón «Execute» para efectuar la acción
El caso del PATCH no lo voy a poder mostrar debido a que este ejemplo no lo trae, pero el mecanismo es exactamente el mismo.
Algo a tener en cuenta, es que no siempre va a ser así tal cual mostré en el ejemplo, dado a que como mencioné en un principio, no hay una sola forma de crear APIs, pueden variar campos, modelos, métodos y demás. Pero la mecánica para testearlas, siempre va a ser la misma.
Espero que les haya gustado y les sirva. Nos vemos en el próximo post!
