You're familiar with the concept of modularity from OOPS, right? So, my introduction is not in this post. 😆

Introduction

An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc. - Wikipedia

There's this fuss about APIs. Everyone has their own definition of what an API is or at least what it's like. But, let me tell you this. Don't trust anyone 🙉

Contents

• Introduction
• Explanation
  • The Dictionary Analogy
  • The Restaurant Analogy
• Conclusion
• References
• Further Reads

Explanation

There is a plethora of analogies. Let's break some of them down.

The Dictionary Analogy

This one's quite right, that an API is kinda like a dictionary. But, according to Wikipedia, there are more than 15 types of dictionaries.

So, it's not just a dictionary. It's a bilingual dictionary; the one we use when we travel to a foreign country.

The dictionary tells us how to communicate with a person who does not understand the language we speak.

This is very much similar to the articles we find on Google when we search for "what does it mean when a dog wags its tail in a clockwise manner". Those articles tell us how to understand the dog. 😁

The Restaurant Analogy

This one might hold true for an MVC architecture but not for an API. Let's see why not.

What do we do when we go to a restaurant? Do we just walk straight into the kitchen and tell the chef what we would like to have for dinner? Well, I certainly don't. 😆

The expectations from us guests are, that we let the waiter know what we would like to have and he will take our order and forward it to the chef. The waiter's job is to keep a track of and serve the orders.

Here, the waiter is just a middleman. The actual message is the dish(es) we order. That is the request which we make.

Coming back to the internet.

GET https://pokeapi.co/api/v2/pokemon/jigglypuff

This is a request. But how could we know that URL?

How do you know that the restaurant serves noodles?

The Menu Card 🎉

That is the API. We can select which dish would we like and tell the waiter to get it served for us. Remember, he's not the one who cooks it.

Similarly, this is an API. It tells us how to talk to the Pokedex and how will it respond to us.

GET https://pokeapi.co/api/v2/pokemon/{id or name}/

Just like that URL has {id or name} in it to tell us that either we could pass the name of the pokemon in the URL or its id, some restaurants also provide us with methods to order, either we could call them or walk-in.

Conclusion

Documentation is important. Developers actually use those. 😁

References

• Application Programming Interface
• MVC Architecture
• Pokedex
• PokeAPI v2

Further Reads

• Understanding a Simple Express Server App | Node.js
• Interacting with a Simple Express Server App | Postman
• "is a plethora" or "are a plethora"?