What is an API? What does API mean? Explained in Simple English
API (Application Programming Interface) sounds complicated, but it just means “function”!
An Analogy
When we are interacting with a computer, we don’t need to care about the inner working of a computer, i.e.
- how does a computer chip work?
- how do the computer parts talk to each other?
- how does programming work?
All we care about is how to use a keyboard and a mouse. In other words, keyboard and mouse are the interfaces for us human to use the computer. This applies to other objects as well. For example, in a car, the steering wheel, brake pedal, gear handle are all interfaces for us to drive a car.
Now, in the programming world, there are also needs for interfaces to interact with software. And we call these interfaces API! Hence the name Application Programming Interface, i.e a programming interface for applications 🎮.
Why API?
In short, API is a set of functions exposed to us so we can interact with a program.
Why do we need API? Well it is the same reason as why do we need a steering wheel in a car? Though it is technically possible for us to drive a car without a steering wheel (via 💪 and sheer determination) but it is simply impractical. A car is far too complex for an end user.
Similar to a car, the main goal of API is to let the end users be able to easily use a particular program. They only need to know how to use the interface / functions, but not the inner working of the system.
API Deep Dive
I would categorise API into 2 groups:
- Programming API
- Web API
Programming API
These are functions provided by the programming language or library.
For example, in JavaScript, we are able to interact with the console via the console API. If we want to log something in the console, we can simply call the log function that is exposed by the console module, or logging an error using the error function, or generic info using the info function:
console.log('heeyy');console.error('something went wrong');console.info('some info');
These functions are collectively known as the Console API in JavaScript.
Web API
In short, web APIs allow web applications connect to each other. Web APIs are a set of functions exposed by a web app so that other users can interact with the web app, without even seeing the source code of the app.
Modern web applications are often dependent on each other. For example, although Facebook and Instagram are 2 different web app, but we can still share our Instagram post to Facebook within Instagram itself. How does Instagram do that? The magic behinds it is….Web API!
So what composes of a Web Application?
A web app is essentially a complex system comprises of lots of functions. Imagine if we have created a great tool that could generate subtitles for any video in any language. Our app becomes popular very quickly and now we got a lot of requests asking us to integrate our service onto other platform. For example, a movie hosting platform would like to use our service to automatically transcribe their movies whenever there is a new upload.
But our transcription service can only work within our app…right?
Well this is exactly where web API solves our problem. Why don’t we expose our transcription service as a function (aka API) so the others can use it externally?
Web API: Behind the scenes
So how does a web API work behind the scene? Let’s take a look at a real world example: github.com
Let’s try to call an API endpoint from Github.
Sample response:
So what is happening here?
- Browser sends a HTTP GET request to github’s server.
HTTP requests have different types of method:
GET — To download or read data. In our case here, we are trying to read a list of licenses from Github.
POST — To create or other miscellaneous operations. For example, login to an app, creating a new Facebook post.
PATCH — To update. For example: updating profile picture.
DELETE — To delete. For example: deleting a comment. - The server receives the request, and run a function to search for all types of licenses from its database.
- Once found, the server sends back a JSON string to the browser and the browser will simply display it. JSON — JavaScript Object Notation is a string format that looks very similar to JavaScript object. It is widely used to transmit data in web API.
In a nutshell, we are simply running a function by sending a HTTP GET request to the Github’s server.
So Web APIs are just functions exposed via URLs by a server.
By using web APIs exposed by another web application, we can leverage features developed by other people so we don’t need to reinvent the wheel.
What about Authentication?
Yes. without authentication or restriction, random people around the internet can easily abuse an app’s API in many ways. For example, by firing 1000 requests per second until the server goes down, or freely view others private information without logging in. You wouldn’t want a random stranger to view your Facebook’s chat history, do you?
Typical API authentication methods
1. Secret Key / API key / Bearer Token 🔑
This is the simplest way for users to authenticate themselves. The concept is simple. Whenever a user calls an API endpoint, the user would include a so-called “API key” in the HTTP request.
An API key is kind of like a password. The server will only process API requests with a valid API Key.
For example, an API request with API key would look something like this:
https://api.mysite.com/posts?apiKey=somesecretapikeyWe are simply passing our API key as a query parameter on our API request!
Although using an API key for authentication is simple, once the key is stolen, it could severely compromise your account.
2. Cookie 🍪
First of all, internet cookies are not edible nor tasty. Cookies are small chunks of data that lives inside the browser. If you are using Chrome, you can view all the cookies given to you by Medium.com in the Application panel in the developers tool.
Cookies have a few common uses:
- Trackers that identify visitors for marketing purposes.
- Security cookies to stop attacks like XSS (cross site scripting).
- Authenticating users. Let’s talk more about this.
When you check the ‘remember me’ box when you login to a web app, the app’s server will give you a cookie to store in your browser. From here on, whenever you try to access any resource via web API, your browser will attach this cookie along with your HTTP request. The server will then validate the cookie in the request to make sure the cookie is the one that it sent to the browser before.
3. JWT (JSON Web Token)
JWT is essentially an encrypted JSON string, where it contains information about the login user.
When a user logins to an app, the server will issue a JWT to the user. The JWT is then passed along with the subsequent HTTP requests to the server.
JWT is short-lived by convention, typically with a lifetime of 15 min to 1 hour. Whenever it is due to expiry. the browser will request for a new JWT from the server.
JWT has the same security concerns as using an API key. Once it is stolen, the hacker can do pretty much anything to the user’s account. However, due to its short-lived nature, JWT is more secure than using an API key, because the hacker only has a minimal amount of time to wreck havoc.
4. Oauth
Oauth is more advanced than the method described above. It is more secure but highly technical at the same time. Check out my other article if you want to learn more about Oauth.
That’s it for now!
Additional Resources
https://github.com/public-apis/public-apis — A list of web APIs that you can start using in your next project.
