Working as a software tester means, among others, understanding how the software works to be able to test it. This is similar to a surgeon. You can’t operate on a patient without knowing how their body works. So as a software tester you need to have at least a basic understanding of how computers/servers/browsers/app etc. communicate with each other. Mainly, how is it possible that you can get information saved in one place visible in a different place?
This kind of communication is usually called API. And because it is so important, I decided to write about the 10 most crucial facts you should know too. For the purpose of this article let’s imagine that people are students, computers are teachers, and servers are librarians.
1) What is API
API stands for Application Programming Interface. That means it is an interface between two applications/computers that enables them to communicate with each other through some program. You can imagine the API as a postal pigeon delivering your request to the other side and receiving what you (hopefully) expect.
In order for the API aka postal pigeon to do its job right there need to be two parties. Also, somebody has to set the rules on how the API/pigeon will do the delivery. These rules will also depend on the type of API used.
API is a type of contract between the parties as well. If one party wants to, for example, know the weather, they have to give the pigeon their postal code. Then the pigeon can deliver the weather forecast in the area of the zip code.
2) What types of APIs are there
There are two most common types of APIs. One is SOAP and the other one is REST API.
a) SOAP API
SOAP stands for Simple Object Access Protocol. It is the older type of API (the 1990s), developed originally by Microsoft. SOAP can use only one format for the message and that is XML (Extensible Markup Language). SOAP API performs operations through a standardized set of messaging patterns. It delivers the message in a specific way called an envelope. This can allow for better security and sometimes less coding. But it is also slower and heavier.
You can imagine it as an old-school postal pigeon that has a certain specific way how to wrap the messages in fancy metal-plated envelopes before delivering them, so it takes a longer time to get there.
b) REST API
REST API means Representational State Transfer. This means a set of architectural constraints, not a protocol, so it is more about accessing data than performing operations like SOAP. It is perfect when you are exposing public API over the internet. It is much faster and you can use it with different formats: JSON or XML.
You can imagine REST API as a young upbeat pigeon that is quick to request and deliver messages in multiple formats (postcard, piece of paper, sticky note).
Although fast and upbeat, there are six architectural constraints for REST API to fulfill. These include:
- The user interface has to be separated from the server storing data and requests managed by HTTP. Imagine that the pigeon is delivering knowledge between teachers and librarians;
- Each request from the client to the server needs to have all information and not rely on the stored info on the server. Teachers have to describe what exactly they want from the librarians otherwise librarians can’t help them;
- Information sent by the server needs to be cache-able to help limit the network operations. Teachers should be able to keep librarians’ knowledge for some time without having to request the same knowledge from the librarians again;
- The information is transferred in a standard form
- clients receive identifiable and requested resources together with some representations (librarians send requested knowledge to teachers as well as sort of a manual on how to use the knowledge),
- clients can manipulate resources through representations from the server (teachers will use the knowledge based on the manual),
- the server provides self-descriptive messages that help the client know how to process it (librarians provide the teachers with some messages on how to work with the knowledge), and
- clients can find hyperlinks to take actions regarding the resources (the knowledge sent includes links so the teachers know what they can do with it),
- Layered system on the side of the server (security, load, etc.) which is invisible to the client. Some librarians are securing the knowledge, some are weighing it before sending, but the teachers can’t see what each librarian does; and
- The server sends optional code on-demand to the client that extends the client’s functionality. Librarians can send extra knowledge if the teachers ask them for it.
3) Who makes REST API (and how it looks like)
The way an API is going to look like is the decision of the back-end developers. They are the creators of the API/pigeons. However, there are certain conventions how an API should look like and most developers thankfully follow them.
a) How is an API made on the back-end
Although there are multiple back-end languages, the general idea is that the back-end developers create a model, a controller, and routes.
- The routes specify how the API/pigeon will look like;
- The controller sets the action for the API/pigeon,
- The model allows the API/pigeon to retrieve the knowledge from the database/librarians and deliver it in form of a view (HTML) to the client/teachers.
b) How does an API looks like
Each API/pigeon consists of:
- an endpoint,
- a method,
- headers,
- body.
There is a root-endpoint https://api.pigeoninfo.com. Then there will be a path mentioning the specific data to access /pigeontypes. The API documentation will mention all available paths so you do not need to guess them. After the path the parameters come, they always follow after the ? sign (so called query string).
In the case of https://api.pigeoninfo.com/pigeontypes?color=grey, we can retrieve only gray pigeons from this API. Similar to the paths, the documentation will also mention available parameters.
4) What are protocols and methods employed by API
When using APIs to retrieve data, we have to follow the protocols or rules of those who made the APIs. If the back-end engineer said that the pigeon can only carry knowledge on a piece of paper then you can’t send it to pick you up a beer. Protocols work the same way. They are rules on how the API will behave and what it can retrieve.
a) HTTP protocol
The most used protocol is HTTP and it stands for Hypertext Transfer Protocol. That means the HTML format is used for writing the data.
b) HTTP methods
The request pigeon will include the version of HTTP (there are four so far) and the method for accessing the data/knowledge for the client/teachers. The most used methods include:
- GET – teachers want to get some data from the other application aka librarians so send a request pigeon to get them;
- POST – the pigeon is bringing some data to be saved in the other application/librarians;
- PUT – the pigeon is changing the data saved in the other application/librarians;
- DELETE – the pigeon is deleting data saved in the other application/librarians.
The response pigeon will include the HTTP version, a status code that will confirm if the request pigeon made it or not, and folders and parameters with the data and how to use them.
c) Status codes
There are 5 classes of status codes. If the back-end developers set them right then you will know that:
- Informational responses (100 – 199) request pigeon made it but the librarians are still working on it;
- Successful responses (200 -299) request pigeon made it and the librarians sent response pigeon back to teachers successfully;
- Redirects (300 – 399) request pigeon was sent to different librarians;
- Client errors (400-499) teachers sent wrong request pigeon;
- Server errors (500-599) librarians are not working today, request pigeon did not make it there.
5) API format
As mentioned above the SOAP API/old-school pigeon uses only the XML. In contrast, REST API/young upbeat pigeon can deliver XML or JSON response.
a) XML
XML stands for eXtensible Markup Language and it is a markup language similar to HTML. It was designed to store and transport data and it is self-descriptive. The tags are similar to HTML but nobody predefined them. It looks something like this:
Most web browsers have a built-in XMLHttpRequest object, which allows you to request data from a server. Thanks to that the XML format can be very handy when exchanging data.
b) JSON
JSON stands for JavaScript Object Notation. It is a lightweight format for storing and transporting data. It is easy to understand as it is self-describing. All data has to be in “key”:”value” pairs, separated by commas. Curly braces hold objects and square brackets have arrays. An example of JSON looks like this:
The JSON format is syntactically similar to JavaScript objects so it is easy convertible into native JavaScript objects.
6) What are headers for
The HTTP headers allow the client and server to send additional information with the HTTP request and response. You can imagine it as a little backpack full of useful info the pigeon gets with every delivery to help the teachers open and use the knowledge.
Headers consist of key: value pairs and are case insensitive. They include various information, among others, whether:
- the data/knowledge is cache-able,
- a cookie can be set to personalize a user’s session,
- the API can be publicly accessible (CORS),
- authentication is defined, and
- authorization credentials are contained.
7) The use of body
The request body in the REST API (payload) is used for the POST, PUT, and PATCH requests. You can imagine it as the request pigeon bringing a specific message to the librarians to save it.
On the contrary, when you have a GET request, you do not use the body but you set all your query parameters into the API URL right after the ? (query string).
8) How to keep API secure
REST API is not as secure as the SOAP one, so you need to secure it. You should think about it as a protection to our postal pigeon so that nobody can steal him and the information it is carrying. There are multiple ways to do that:
a) HTTPS
Always choose HTTPS. That is achieved by using SSL (Secure Sockets Layer). Its installation establishes authenticated and encrypted connections between the browser and client. You can imagine it as turning the request and response pigeons into eagles so nobody can know that they are postal pigeons while on delivery.
b) Password hash
Always hash all password. You can imagine it as a key owned by students who want to unlock the knowledge that the pigeons deliver from the librarians. However, the key is magical and scrambled into a spoon so that nobody knows it is actually a key.
c) API key in URL- NEVER!
If you are using an API key, never expose it on URL. This applies to any passwords, usernames, and session tokens as well. Neither of them should be displayed in the parameters of the API. And when speaking about an API key, those are used between applications for recognizing each other (teachers will send API keys to librarians when sending the request pigeon for info; good practice is including the API key in headers or body). For example, your favorite takeout food application includes google maps in it with an API key.
d) OAuth
When possible, use OAuth (Open Authorization). This is a standard for the authorization of resources. OAuth is used to authorize and authenticate the users while the API key is used to authenticate and use the applications. This is how librarians and teachers can find out if students are authorized to have access to the knowledge. OAuth makes it possible for users to sign into one application/platform and then view data or perform actions in another platform, for example singing into other applications with your Facebook profile.
e) Timestamp and parameter validation
Adding a timestamp into the request headers is a great way to provide security. The server will be able to control whether the request was sent within a reasonable timeframe (1-2min). You can also include parameter validation. If there are strong validation checks on the first step, the request can be rejected as soon as the validation fails.
9) How to make an API call
Front-end applications make the API calls (a browser in-built web API) and the process is called consuming. You can imagine it as the teachers eating the response pigeon.
When the user interface is coded in React.js or Vue.js, the REST API is usually consumed either with Axios (a promise-based HTTP client) or Fetch API (a browser in-built web API). Axios is compatible with more browsers than Fetch API is.
10) How to test API
If you want to see if our request pigeon made it to the librarians, I would recommend testing it in Postman. There you can choose the HTTP method, insert the API, add headers, etc., and just click send.
If you want to automate the API testing in your project, then Cypress.io is a great way to go. Again you can test it with the headers, choose specific HTTP methods, use API keys etc.
So there you have it. I hope you liked this article and learned something from it, at least you got a basic understanding of how computers communicate with each other. If you would like to learn more about how software testing, check out my other articles too. And if you have some comments on this article I would love to hear them! 🙂
1 Comment
Thanks. Really simplified, liked the analogy.