Types of API calls
Some calls to APIs can change things on the server, while others return data without changing anything. It is important to distinguish between these different types of calls when testing or designing an API. There are a few different terms that are used to describe these differences. In order to help you understand these terms, I will use an analogy using Lego pieces.
Imagine that there is a table with a couple of Lego pieces on it. Now imagine that the guy on the right in the following diagram is me. I represent an API, while the Lego pieces represent a server:
Figure 1.1 – Representation of a server and a client
You are going to be the client in this imaginary relationship. This means you can ask me to do things. You ask me to tell you what color the top Lego piece is. I reply that it is blue. This is an example of an API request and response that is safe. A safe request is one that does not change anything on the server. By asking me for information about what is going on in the server, you have not changed anything on the server itself.
There are other kinds of API calls that can happen though. Imagine that you gave me a green brick and asked me to replace the top brick on the stack with the green one. I do that, and in doing so I have changed the server state. The brick stack is now made up of a yellow, red, and green brick, as shown in the following diagram:
Figure 1.2 – New server state
Since the server has changed, this is not a safe request. However, if you give me another green brick and ask me to once again replace the top brick with the green brick, nothing will change on the server. The stack will still be made up of a yellow, red, and green brick. This is an example of an idempotent call. API calls that return the same result no matter how many times you call them are known as idempotent.
Let's imagine one more type of call. In this case, you give me a green brick and ask me to add it to the top of the stack. I do that and so now we have a stack of four bricks. This is clearly not a safe call since the server has changed, but is it idempotent?
The answer is no, but take a second to think about it and make sure you understand why this call would not be idempotent.
If you are struggling to see why it is not idempotent, think of what happens if you repeat the same request again. You give me another green brick and you ask me to add it to the top of the stack. If I do that a second time, is the brick stack still the same as it was after the first time you added it? No, of course not! It now has five bricks and every additional brick you give to me to add to the stack will change it. An idempotent call is one that only changes things the first time you execute it and does not make any changes on subsequent calls. Since this call changes something every time, it is not idempotent.
Safety and idempotency are important concepts to grasp, especially when it comes to testing APIs. For example, if you are testing calls that are safe, you can run tests in parallel without needing to worry about them interfering with each other. But if you are testing calls that are not safe or idempotent, you may need to be a little more careful about what kinds of tests you run and when you run them.
Now that you have an understanding of some of this basic terminology, I want to talk about the structure of an API. However, it will be a lot easier to do that if we have something concrete to look at, so at this point let's take a brief pause to install Postman.