Postman: Pruebas de API como si fuera un niño [parte I — analogías]

Mejor es que no prometas, y no que prometas y no cumplas.

Eclesiastés 5.5

He vuelto de nuevo.

Antes del tema en sí, me gustaría informarles que estoy tratando de escribir mis publicaciones en Portugués en Español y Inglés para forzar estas habilidades un poco, así que si cometo errores gramaticales más serios, sus comentarios serán bienvenidos.

Déjame explicarte un poco de dónde vino esta idea:

Estoy trabajando en una empresa interesante de Brasilia llamada AIS centrada en soluciones móviles, Coaching ágil, Microservicios, SOA, Big Data. Trabajamos con muchas lenguajes de servidor como Java, Kotlin, NodeJS, Scala, R, Ruby, entre otros.

Con un enfoque centrado en chapters y guilds, comenzamos a organizar y ofrecer foros para la difusión del conocimiento. Lo que me di cuenta fue que algunas palabras eran confusas en el significado entre algunas personas: API por ejemplo.

Empecé a pensar en cómo difundir el conocimiento, sin embargo, sin hacerlo aburrido y confuso como un discurso de la profesora de Charlie Brown.

La idea de libros de Head First sería la forma más excelente de compartir conocimiento con esa gente.

Comencemos con una analogía para las API: el camarero. Aprendí esta analogía en mi compañía, y decidí expandirme en otros escenarios. Utilizaremos API REST para ejemplos futuros.

Nuestra interacción con un camarero en un restaurante es similar a una interacción con una API. En este ejemplo, nosotros, como clientes de un restaurante o consumidores, interactuamos con un camarero (API). El camarero interactúa con otras personas para que la solicitud llegue a nuestras manos en un momento determinado.

Otro punto interesante a destacar es que hay otras interacciones en el restaurante de las que a menudo no nos damos cuenta, como la interacción con la parte financiera, la solicitud de comida del distribuidor, etc. Por lo tanto, la API del restaurante no está restringido a quienes ordenaron su comida.

Lenguajes de backend y tiempo de entrega (SLA)

Es interesante notar que la mayoría de las veces no tenemos acceso a cocineros de restaurantes. Si son japoneses, brasileños, indios, etc. no es un gran problema para nosotros, siempre que la comida llegue a nuestras mesas.

En esta analogía, la cocina sería nuestra lenguaje de backend que podría haber aumentado o disminuido los recursos que se dan los días de la semana y las vacaciones (escalabilidad). Otra cosa importante es que el tiempo de entrega de nuestra solicitud nos influiría en nuestra experiencia con el restaurante, algo así como el Acuerdo de Nivel de Servicio (SLA).

Código de estado HTTP

Las API REST deben seguir estándares y convenciones como el Código de estado HTTP. Si aún no lo sabe, eche un vistazo a este sitio y trate de no “perder” durante al menos 15 minutos.

Entonces imagine la siguiente conversación en un restaurante y su “estado”:

Cliente: Camarero, ¿podría traerme un poco de agua?

Camarero: OK (Código de estado HTTP: 200).

Cliente: Camarero, ¿podría traerme jugo de granadilla?

Camarero: Por el momento no tenemos jugo de granadilla (Código de estado HTTP: 404).

Cliente: Camarero, ¿podría traerme jugo de naranja?

Camarero: Perdón por las molestias, pero tuvimos un problema en nuestra cocina y no vamos a conseguirlo (Código de estado HTTP: 500).

Especificación API

Imagine que llegamos a un restaurante japonés y solicitamos muchos sushi, y el camarero dice que todavía no tienen sushi (Código de estado HTTP: 501). Luego pedimos una porción de sashimi, y el camarero dice que todavía no tienen sashimi tampoco (Código de estado HTTP: 501).

Podríamos seguir preguntándole al camarero varias veces y esperar su respuesta, o ser más asertivo, y pedir: ¿Podría traernos un menú por favor?

En ese caso, el menú funcionaría como una especie de documentación o especificación de lo que ofrece el restaurante.

Hablaremos más sobre las especificaciones y documentación de la API en la segunda parte de esta publicación, pero por ahora, esta analogía es suficiente.

Ya sabemos lo que sucede cuando el cliente hace una solicitud al camarero que no se puede procesar, pero ¿alguna vez se ha imaginado el problema de un menú anticuado?

Una vez, fui a un restaurante con mi esposa, y después de pedir una bebida específica del menú, recibimos algo completamente diferente.

Le dijimos al camarero que no era lo que habíamos pedido del menú. El menú no estaba actualizado según el camarero. Ya no tenían la bebida y nos devolvieron otra cosa.

Nos hicieron una fórmula similar. En resumen, una experiencia no muy agradable porque generó una expectativa en nosotros. Era mejor no tener el menú de lo que está anticuado.

En el universo de las API, esto es muy común. A menudo, la documentación de múltiples API está anticuada en comparación con lo que debería hacer, lo que dificulta que el cliente interactúe con la API.

¿Qué hemos aprendido hasta ahora?

• Un camarero sería una API de interacción con una cocina y otros servicios en backend.
• El tiempo de entrega de nuestro pedido (SLA) en el restaurante impacta en la experiencia que tenemos con él.
• Existe una convención de estado para nuestra interacción con las API.
• Documentar su API puede hacer que sea más fácil para el cliente interactuar con ella.
• No documentar su API puede ser un problema para el cliente.
• La documentación incorrecta de su API es un problema aún mayor. Sería mejor evitar generar una expectativa equivocada.

Terminaré esta publicación aquí, en la siguiente parte hablaremos sobre la prueba de API con Postman. Nos vemos.