API testing - concepts in depth

Article based on real life feedback. So, challenge accepted!

You should maybe start with a simple example of what API is, like a restaurant - customer, waiter and the cook

The restaurant

• Is the bit of code that does some logic. But maybe I'll have to go back a few steps because there is some context missing. Before the payload (the information) gets to an API there are some systems which can get a little bit of attention. There is the network (internet or same computer, doesn’t matter, but there is something in between). But between the network and the code there is a server. The server’s responsibility is to accept connections and then based on the url+verb send those connections to a piece of code.
• Let’s take GET http://demo.com/user/3 as an example. The verb is GET. Is the type of request. It is important because http://demo.com/user/3 can also support a DELETE and a PUT for updates. And those will point to different bits of code.
• The other important part is /user/3 . This is a path. So the server has to look for an endpoint that responds to /user and accepts a value. Currently almost nobody checks if 3 is a number or a letter or anything else.

That’s how something we send from Postman gets inside a server and inside the bit of code we care about.

The customer

• This would be the request itself together with everything it has. If the customer has clothes and bags and other items. The request has payloads and headers and network information.

So, the customer enters the restaurant.

The waiter

• This one is a little bit more complicated because it in real life the waiter both sits the customer at a table but also serves the customer. It gets complicated because the waiter in this simplistic example represents both the CPU thread and also a session of that customer.
• The session would be what happens with the customer while it was in the restaurant this time + whatever happens with the same customer in the future IF the restaurant recognizes the same customer. Usually sessions have a lifetime and they are designed to create a comfortable environment with most recent information still fresh for that customer.
• The thread however is some processing power dedicated to resolve this request. This is why, when there is a big number of requests to a server, some don’t even make it past the entrance door. There is no more processor available to accept them. This is a simplification. Is not fake or wrong, but there are also other technical things which I will not include because they are case by case.

The cook

1. Correct technical explanation:

   • Well here it gets really strange :D excuse the smiley. Technically the cook lives inside the waiter unless specifically coded otherwise. Let’s say the cook is the code inside the endpoint. The IFs, ELSEs, variables, WHEREs and other statements.
   • We can say that the cook is the waiter who changed his uniform while in the kitchen.
   • But as soon as the cooking is done, Good or bad. Success or failure. It will change the uniform again into waiter and invite the customer out the door. That’s the response we get from the server.

2. Not so correct technical explanation but one you could think is true:

   • The waiter goes to the kitchen with the order and the cook fetches data from the database
   • The waiter brings the data to the request and the request does the logic
   • As soon as the logic is done the request goes home out the door with the response

Why #2 is not correct?

• The thread of the request is never put to sleep. Is always active. Even in asynchronous processing. There is too much overhead involved for a “waiter” to change tables/customers. There can be a load balancer but that is outside the restaurant in our example. Once assigned to a piece of code, that piece of code has to finish.
• Sometimes the waiter can do nothing (be idle) and accept bits of work from other processes. But in the computer’s memory the name of that waiter still exists (thread id). And every few nanoseconds (the processor tick) the processor will try to see if the thread can return to its initial work or try to kill that thread to free up the resources. But our thread cannot die until the response has not been returned or until the request has not stopped due to timeout, cancellation or a crash. So in reality our “waiter” will never serve other tables even if from time to time it can do some math or string manipulation for other bits of the program.
• There is no “eating time” either because the request looks more like an onion. Outside we have the incoming request. Inside it we have the thread. Inside it we have workers. Inside it there is data. So as soon as the workers are done, the thread returns the response and the server closes that connection.

Conclusion:

Maybe APIs should be explained with onions rather than restaurants.

Credits:

• Initial text: gabriel@qality.tech
• Initial feedback and idea: Miss M.