What is an API? A simple explanation …

Sometimes people ask me programming questions, and I am driven to explain it in the simplest possible way, because that’s how I’d have liked to be taught. My answers when I’m done are sometimes so good, I try to share them as they are with others who might learn from it.

Here’s one such by @MrVON_, posted with his permission:

Please can you try and explain to me simply what APIs are?

What do you think APIs are?

I have no idea. Which is funny because I just worked with them on a simple Django project.

I know what it stands for. Application Programming Interface. But that’s where it ends.

You know how to drive?

Nope. I don’t.

No wahala!

A car’s engine is complicated. Lots of parts, fitted together.

However, no driver needs to understand all the engine’s parts to drive the car.

That’s because the car has a simple interface that lets you drive it. This is the steering, gear, brake, and clutch.

An interface is just a way to communicate with something.

Your computer has an I/O interface, that takes many forms including your keyboard, mouse, screen, sound speakers, etc.

So interfaces are not just for input, they’re also for output. E.g. In a car’s instruction manual, there’ll be a section for what to do about weird car sounds. If your car’s making a grrr grrr sound, it could mean a part of the engine is bad. The car’s sound becomes part of its output interface.

Does that make sense? Or should I give another example?

So in a nutshell, interfaces help us work with machines which we otherwise may not be able to work with.

Is this correct?

Exactly!

Yay!

**You for open school o 😭😭😭😭👏👏👏👏👏

Now, Application Programming Interfaces help us work with programs.

Please give me an example

E.g. in unix, there’s the “cp” program that copies a file or directory from a source to its destination. To work with it, you’d type “cp <source-path> <destination-path>” in your terminal.

Be sure to replace <source-path> with the actual file path of the file you intend to copy, and <destination-path> with your intended location for the file.

This is already an interface for working with the “cp” program. *😄

In fact, it’s the “cp” program’s API

**Wow. Would’ve loved to use this but I use Windows. 😶

Windows has the “copy” command

You can see a full description of a unix program’s API by typing “ — help” after the program name. e.g. “cp — help” For windows, type “/?” after the program’s name. E.g. “copy /?”

Oh okay. Thanks.

I’ll try that soon enough

By the way, you can download Termux from playstore on your Android to get a bash terminal. You might find it helpful. I'll try to give the windows equivalents of stuff, but I'll give bash first.

Okay. On it.

Now, the “cp” program runs locally on your computer.

On the web, you’re working with a program that lives on an entirely different computer across a network.

Such a computer is called a server, and your own computer is called a client.

These two computers have to communicate somehow, and they use a common language format they can understand known as a protocol. For your browser, this protocol is HTTP (Hyper-Text Transfer Protocol).

Are you still with me?

Sure

There are many other protocols, but we’ll skip them for now.

FTP. I’ve used that one.

Aha! FTP is one of them.

A protocol is just a set of rules that both computers can understand, so that when one encodes data and sends over the network, the other can decode it and make sense out if it. Shikena!

**Simple 😂

**Makes more sense. 😂🤣

**All these big big grammar. 😭

Loool!

So a client and a server have to communicate

The client is my browser shey?

I’ve read these things before. I’m just happy they’re getting clearer now. The relationship I mean.

Yup, your client is usually the browser, but it can also be any program really, that can send data over http.

Okay. Noted.

In bash, there’s a program called “curl” that helps you make http requests.

If you typed “curl https://www.google.com “, it’d print out the HTML content of the google home page.

I just installed curl on the app you told me to download and ran “curl http://google.com”

Nice, did it work?

Kinda!

Let me send you a screenshot.

Yup, that’s it

See the <HTML> <HEAD> … ?

Yeah. Seen.

Now, let’s go to how HTTP works … Keep in mind that requests are sent from the client to the server.

We have things called methods like:

— GET (retrieve data) — POST (create data) — PUT (update existing data) — DELETE (remove data) — and more

These methods are used as labels for requests.

E.g. “curl [https://www.google.com](https://t.co/y1vSXJ9jdD)” makes a GET request to retrieve the google home page.

Okay. Noted. Http Verbs

That’s what the book I read called them.

Aha, nice!

We also have URLs which are addresses for resources. E.g. https://www.google.com is the address for the google home page.

**Yes. When I get confused, I’ll inform you 🤣🤣🤣

So far it’s all been very clear.

For POST, look at twitter for example.

When I click “SEND” on this message, it could make a POST request to a URL like https://twitter.com/messages/send

But who does it send the message to?

POST requests have a “body” that contains extra data. This data can be in any format, so we have a header called “Content-Type” that tells the recipient what format the body’s data is in.

An example format is “text/plain” which is just plain text.

Other formats are “application/json” which sends JSON data, “text/csv” which sends comma-separated values, and many more.

Sorry, I didn’t mention headers before.

An HTTP Header is a part of the request that carries extra information about the request.

It should be noted that it is called a “header” because it is the first part of every HTTP request.

Aha. Much clearer now. Thanks.

Popular headers are “Content-Type”, “Content-Length”, “Status”, etc

So, my twitter DM message’s request can have a body like:

{ “message”: “this is my message to you”, “to”: “@MrVoN_” }

and a Content-Type header value of “application/json”

The server would take that, and create the message. Each message would have an ID, so it’d live at a URL like [https://twitter.com/messages/12345](https://t.co/c1nTWz8dfE) where 12345 is its ID

If I ever wanted to delete the message, I’d send a DELETE request to https://twitter.com/messages/12345

It’s almost the same with if I wanted to edit a message using PUT, with the difference being that PUT requests have a body that contains the new information, and DELETE requests don’t.

Okay.

Pardon me

Sure, waddup?

Lemme ask a question which will make me understand this better.

I previously thought that APIs are services from companies which anyone can use in their own products.

We’re getting there

Oh okay. Continue then.

Your previous explanation is also very clear

Now that you understand HTTP, clients and servers … and you know that an API is the way to communicate with a program … then you know what Web APIs are, even if you don’t know it yet.

They’re simply a way for a client to communicate with a server program over the web, via HTTP.

**True I do. Thanks to you. 😊

Remember when I said any program can be a client? It’s the same for servers, as long as it implements HTTP, and listens for requests over the network.

Yes.

Oh.

I’m not sure I understand the servers own role here.

Clients send requests and servers answer them and respond.

Yep, the server responds to requests.

So, a company like Hotels NG has its own server.

They’ve coded a bunch of ways to handle requests for things like creating, editing, deleting, booking hotels.

This is Hotel NG’s Web API as long as it’s accessible over the web.

Wow.

That’s so cool.

**So how does one make use of it? 😶

As an example of course.

It may or may not be open to people outside of Hotels NG staff.

Openness here means the public having access to use it.

For a closed API, there are many ways to secure it, but that’s outside the scope *😋

Even with an Open API, like Twitter’s for instance, you’d want to have a way to ensure it’s not abused. Cos someone could set up a million programs to send multiple requests to your server, and crash it.

How to do that is also out of scope.

Twitter uses a rate limiter though, so you can only make about 2,000 requests per day, after which all requests from your App will be blocked.

That’s why you must register a twitter app and get an access token before you can use their API.

So, you’re good?

Yeah. Tried using their API but couldn’t because they had to review it and all that.

I have a clearer picture now than I did before the conversation. So that’s a good thing.

I’ll ask a more concise explicit question soon enough. Perhaps tomorrow.

So folks, till the next time @MrVON_ asks a question, bye!