What’s an API? Explained with a 2 Min Example
By: Ran, Reine
Tags: API, Software Engineering, Software, Programming, Software Development

What’s an API? Explained with a 2 Min Example

That anyone can try out (in 2 minutes)

The author really tried :,)

I very recently got asked the question “What is an API” by a friend of mine who’s from a business background and when I explained it, I realized the only point in time when I ACTUALLY had a good understanding of what it is was when I made an API call.

That’s why in this article, I’m gonna try explaining what an (Application Programming Interface) API is with an easy-to-follow example.

But before that let me just copy paste the textbook definition of what an API is for the sake of completeness :)

According to Wikipedia,

An application programming interface is a computing interface that 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.

There’s also this very common term buzzing around — REST API. REST stands for representational state transfer and is often contrasted with SOAP (a protocol that’s more complex). REST is a lightweight set of architectural principles and the APIs designed for REST (RESTful APIs) would return the request with data in these formats — HTML, XML, plain text, and JSON. JSON is most common and preferred since it’s easily readable by computers and also humans. We’d be focusing on REST API.

Okies and with that, let’s get started!

What we’re gonna need for this guide:

Some online API data set (we’re gonna be using this link which returns you the design applications lodged with the IP office of Singapore). I’m using this because I find this site really beginner friendly and hassle-free. Something to make an API request. I’m using Postman since I already have it installed (and it’s interface is really easy to use too). But you can use an online API request tool or other applications like Insomnia.

Alternatives for 1 and 2 will be listed at the end of this article.

So if you click on this following link — https://data.gov.sg/dataset/ipos-apis, on page load you’d see:

Fig 1 — Screenshot taken by Author from Data.gov.sg

The fun thing with this site is that you can click on the “Try it out” button and try making the GET request right on this site. So after clicking that,

Enter a date — Screenshot taken by Author from Data.gov.sg

We get status 200 and the data returned in JSON format — Screenshot from Data.gov.sg

That’s it. We just made the GET API request.

What if the site we’re on don’t have such an interface?

Then we’ll have to use an API requester. (I’m using Postman in this case coz the logo is really cute + user-friendly interface)

On Postman, either create a new request or untitled request:

Untitled request

We then paste in the request URL and the query parameters as instructed in Fig 1.

Paste in the query parameters and the request URL

We then get a response and the JSON response is nice presented to us:

Returns a 200 OK (means it’s successful)

It may be worth mentioning that you TECHNICALLY can also just throw the link (https://api.data.gov.sg/v1/technology/ipos/designs?lodgement_date=2019-10-15) in your browser and you’ll get the same response:

The problem is that it’ll look really messy and usually we’d make API calls in our applications or smth and we’ll process the JSON object/response we get back and do something with it.

Other possible returns — Taken from AWS — link

We got a 200 OK and that means that our API request got successfully handled and returned. Depending on what request you make, you can get other types of responses listed in the table above.

There are other HTTP methods like POST, PUT, DELETE and PATCH but I find myself using POST, GET and DELETE most often. If you’d like to read more about these check out this link.

I think one of the things that I found confusing at the beginning was the whole “Params”, “Authorization”, “Headers” and stuff. We’ve demonstrated how Params are used in our example above so I’d briefly mention one common use case of headers — for authorization.

You saw how easily we just accessed that online data set through a simple API request above. What if we only want specific people to access it or make it more private?

The answer is to use Authorization Headers.

So the client making the request will have to provide the correct credentials when making the request. The server will check if it is correct or wrong. ONLY if the credentials are correct then a 200 OK will be returned with the requested response body.

That’s it for this article! I really hope it was informative :)