top of page

The API, the Webservice & a short explanatory Story for the non-programmer - Part 1

Since the internet boom took place, You must be hearing a lot about an API, which stands for "Application Programming Interface". It's like the umbrella corp of resident evil movies that are present everywhere (on the internet) & are extensively used to perform all or any kind of tasks; bad analogy but sounds cool.

Ladoo & the API Toy Story

Once upon a time, there was a little girl named 'Ladoo' who loved to play with her toys. One day, she had a brilliant idea to make her toys talk to each other, to make her dinner party exciting with interactive friends.

Ducktales's webby playing with her toys

Ladoo had a range of toy animals like lions, Zebra, Giraffe, and even a Unicorn, but they didn't know how to communicate with each other. So, she went to her papa, who was a programmer and asked him for help. Her papa told her about APIs, which were like a special language that different computer programs could use to talk to each other. Ladoo was intrigued and her papa further elaborated that APIs were like secret codes that two programs could use to communicate with each other, even if different people made them. It was like a set of rules that they both understood.

Ladoo thought for a moment and said, "So, it's like when I tell my mama to order Biriyani online and she looks at a menu with different options & multiple ingredients i.e. rice, vegetables, flavors, etc, and chooses what we want to order. The website then uses those choices to make our Biriyani, right?". Her dad smiled and said, "Exactly! Just like the Biriyani website, APIs provide a set of instructions that one program can use to ask another program to do something. In the case of your lion & Zebra, we can create an API that tells them how to talk to each other, so they can play together."

Ladoo was excited and helped her papa to create the API. Now, her Lion and Zebra could communicate with each other, and she had even more fun playing with them!

From that day on, Ladoo became fascinated by APIs and how they could be used to connect different programs together. She even started making her own APIs for her other toys, creating a whole world of interactive and connected playthings.

The End.

How API works

The above diagram simply explains how API works. System 1 requests a piece of information, and the program in System 2 works on it and sends the information as a response to System 1. And the method they used is called API - that's simple. It can be online, offline, or internal to the system.

Now, What is Web Service?

Here the Web is the Internet whereas the Service is the API; So web service is the API that uses the Internet. We can conclude that all web services are APIs but not all APIs are web services. To dig into the technicality of it;

  • To format data over the internet we use XML or JSON

  • To transfer that data we use API protocol as REST, SOAP, or XML/RPC

We will further discuss this in detail as we learn more about the APIs.


To send the API over the internet as a web service we use a protocol called HTTP. Just simply look at the URL of this web page it starts with HTTP, which stands for HyperText Transfer Protocol.

The regular text does nothing whereas the hypertext guides the link to the Google server and how it should be done is "transfer protocol". In the above HTTPS, S stands for secure.

HTTP is divided into the following parts both for request and response (refer to image 2)

  • Start Line

    • Request: Version i.e. HTTP1.1, method, parameter, folders

    • Response: Version i.e. HTTP1.1, status code

  • Headers

    • Request: Host e.g. -, token

    • Response: Cookies, HTML

  • Blank Line

    • Its nothing just to separate the header from the body so the program knows

  • Body

    • Contains the information that needs to be sent & to get the required response

Start Line

Let's consider the following link to search biriyani on Google;

If you directly search in the Google search bar, a long URL will come but till biriyani, as shown above, will work out, you can try clicking the above link. Let's decode it; the below-stated info can be seen by right-clicking on a web page > inspect > network tab.

Network tab of inspect web page of google

The general structure of the start line;




Start Line, Request Line

​Start Line, Response Line, Status Line

HTTP Version




​Many but these are mostly used as GET (get information), POST (Create), PUT (Change/Update), DELETE


API Program folder location

Yes (e.g.: /search)



Yes (e.g.: ?q=biriyani)


Status Code


Yes (e.g.: 200 - OK)


Method (space) API Program Folder Location + Parameters (space) HTTP Version

HTTP Version + Status Code


GET /search?q=biriyani HTTP/1.1

HTTP/1.1 200 OK

*So the above example states that when we search for biriyani in Google; It gets the information by going into the search folder of the Google server and checks for the biriyani file and sends the information as a response with the status code 200 which means Great! we found it.

Status Codes

Google 404 error, the website was not found

Following is a short note on status codes which are used to troubleshoot the API calls;

  1. 100s: Informational response - The API has received your request and the process is continuing

  2. 200s: Sucess response - Your request has been received and accepted

  3. 300s: Redirection response - Further action or information is needed

  4. 400s: Client error - An error has occurred and it originated on your end

  5. 500s: Server error - An error has occurred and it originated on the server's end.

Common error codes

  1. 401 - You don't have the authorization to view the data you have requested. Check API and application permissions

  2. 404 - Server can't find the resource that you referenced. Check the data source URL

  3. 405 - The resource that you're referencing doesn't accept your API call method. Check method & location.

  4. 500 - Trouble accessing the server. Clear cache and review configuration.

A small note on Idempotent:

Idempotence, in programming and mathematics, is a property of some operations such that no matter how many times you execute them, you achieve the same result. So if you analyze the method in the request its idempotence is as;


Idempotent? i.e. Safe to repeat










To know more about the header fields check List of HTTP header fields.


You can check for the various kind of content that can be sent in List of HTTP header fields, for example, if we check for Content-Type > Media Type, we can send various types such as image, audio, video, etc.

HTTP, Stateless & Cookies

Ladoo is playing a game of tag with her friends. Each time she tag someone, she had to start all over again and tag someone new. She can't remember who she had already tagged, so she had to start fresh each time. That's kind of like how HTTP works.

Each time your computer sends a request to the server, it's like starting a new game of tag. The server doesn't remember anything about your previous requests. It just sends back the information your browser needs to display the page, and then it forgets about you.

So HTTP is like a game of tag where you always start fresh each time. That's what we mean when we say it's "stateless." There's no memory of previous interactions, so each request is treated as a new one.

So now you must be wondering how Amazon seems to remember where we left off; that's by Cookies, not the ones we eat but by storing pieces of information on the browser in the form of the session ID, tokens, etc. Just a note, cookies are not executable and don't store passwords.

application tab of inspecting a amazon page for cookies information

I will end this article with a note on the benefits of HTTP being stateless as stateless infrastructure is highly scalable, less prone to crashes i.e. resilient, and less memory is required to execute tasks.

Further on the next article will discuss the ingredients of a recipe that makes the food delicious in comparison to API's ingredients that makes it work flawlessly.


All the related articles for "The API, the Webservice & a short explanatory Story for the non-programmer"



Image 1: Webby from Ducktales - Disney Hotstar

Image 3: Inspecting the page of Google - Raj Khandelwal

Image 5: Inspecting Amazon web page for cookies - Raj Khandelwal



bottom of page