Postman: APIs' testing as if I were a child [part I — analogies]

It is better not to make a vow than to make one and not fulfill it.

Ecclesiastes 5.5

I am back again.

Before the topic itself, I would like to inform you that I am trying to write my Portuguese posts in English and Spanish to force these skills a bit, so if I commit any more serious grammatical errors, your feedback will be very welcome.

Let me contextualize you a little where this idea came from:

I am working at an interesting Brasilia’s company called AIS focused on mobile solutions, Agile Coaching, Microservices, SOA, Big Data. We work with a lot of server languages like Java, Kotlin, NodeJS, Scala, R, Ruby, among others.

With an approach focused on chapters and guilds, we began to organize and deliver forums for dissemination of knowledge. What I had realized was that some words were confusing in meaning among some people: APIs for instance.

I started to think about how to disseminate knowledge, however, without making it as dull and confusing as a speech by Charlie Brown’s teacher.

Head First’s books idea would be the more excellent way to share knowledge with that people.

Let’s start with an analogy for APIs: the waiter. I learned this analogy in my company, and I decided to expand on other scenarios. We will use REST API for future examples.

Our interaction with a waiter in a restaurant is similar to an interaction with an API. In this example, we as a customer’s restaurant or consumers interact with a waiter (API). The waiter interacts with other people so that the request we requested comes to our hands in a given time.

Another interesting point to note is that there are other interactions in the restaurant that we often do not realize, such as the interaction with the financial part, the distributor’s food request, etc. So the restaurant’s API is not restricted to those who ordered their food.

Back-end Languages and Response Time (SLA)

It is interesting to note that most of the time we do not have access to restaurant cooks. Whether they are Japanese, Brazilian, Indian, etc. is not a big problem for us, as long as the food arrives at our tables.

In this analogy, the kitchen would be our Back-end language, which could have increased or decreased resources are given days of the week and holiday (scalability). Another important thing is that the delivery time of our request would influence us in our experience with the restaurant, something like the Service Level Agreement (SLA).

HTTP Status Code

REST APIs should follow standards and conventions such as HTTP Status Code. If you still do not know this, take a look at this site, and try not to “lose” for at least 15 minutes.

Then imagine the following conversation in a restaurant and its “status”:

Client: Waiter, could you bring me some water?

Waiter: OK (HTTP Status Code: 200).

Client: Waiter, could you bring me some passion fruit juice?

Waiter: At the moment we are not having passion fruit juice (HTTP Status Code: 404).

Client: Waiter, could you please bring me some orange juice?

Waiter: Sorry for the inconvenience, but we just had a problem in our kitchen, and we’re not going to get you (HTTP Status Code: 500).

API Specification

Imagine that we arrive at a Japanese restaurant and request for a lot of sushi, and the waiter says he does not work with sushi (HTTP Status Code: 501). We then ordered a portion of sashimi, and the waiter says he also does not work with sashimi (HTTP Status Code: 501).

We could go on asking the waiter several times and wait for his answer, or to be a more assertive, request for the restaurant’s menu.

In that case, the menu would function as a sort of documentation or specification of what the restaurant offers.

We’ll talk more about API specifications and documentation in the second part of this post, but for now, this analogy is enough.

We already know what happens when the client makes a request to the waiter that cannot be processed but have you ever imagined the problem of an outdated menu?

Once, I went to a restaurant with my wife, and after asking for a specific drink from the menu, we received something completely different.

We told the waiter that it was not what we had ordered from the menu. The menu was outdated according to the waiter. They no longer had the drink and returned another thing.

I questioned him that the specific drink was on the menu. He tried to do a similar formula. In short, a not very pleasant experience because it generated an expectation in us. It was better not to have the menu than it’s outdated.

In the APIs’ universe, this is very common. Often the documentation of multiple APIs is outdated compared to what it should do, which only makes it difficult for the client to interact with the API.

What have we learned so far?

• A waiter would be an interaction API with a kitchen and other services at Back-end.
• The response time of our order (SLA) in the restaurant impacts on the experience we have with it.
• There is a status convention for our interaction with APIs.
• Documenting your API can make it easier for the client to interact with it.
• Not documenting your API can be a problem for the client.
• Incorrectly documenting your API is an even bigger problem. It would be better to avoid generating the wrong expectation.

I will end this post here, in the next part we will talk about testing APIs with Postman. See you.