API : The Less Scary Approach

API is a set of functions and procedures that allow the creation of applications which access the features or data of an operating system, application, or other service

— Google

Application Programming Interface (API) is a set of subroutine definitions, protocols, and tools for building application software…

— Wikipedia

These definitions are just combinations of multiple unfamiliar { scary } terms which most likely scares you at first read and you then end up spending a whole day trying to look up every scary term, most times forgetting why you were there in the first place, the chain just never ends :D.

This happens to everyone. What you should never do is give up. Well we are here to discuss API in a less scary way, let’s get down to business.

To Do:

• What API is.
• Why API.

The Magnificent, “Application Programming Interface”, highly exalted in the previous definitions above is simply a MESSENGER. Yea what a shocker! Think of this guy { API } as a WAITER. You go to your favorite classy restaurant to buy food, you gotta place your order { make a request } somehow right? Yea, that guy that walks up to you with list of MEALS available is the WAITER { API }. The nicely suited guy takes your order, goes to the kitchen to get your dream food and comes back with the ACTUAL MEAL you ordered.

Yea, before the APIs, how have requests been made?

Good Question! Take a look at your cheap restaurants, where there are no WAITERS, no MENU list, you just walk straight to the kitchen to get what you want. I think we all know how messy and inconvenient that can get, lots of customers barking their orders, each struggling to get attention. You don’t want to be caught in that mess.

Well, before APIs, clients interacted with the datastore directly which has lots of downsides to it, NOT SAFE.

In computing, APIs takes the request from the User { client } of an APP { Web, Mobile, etc. } to get / send something(s). Say you just ordered for a MacBook from an online store. The online store’s API takes the order information and sends to the Server to process the order, then returns with a response from Server, notifying you whether it was successful or not. The Data has to be represented in a way { format } both the APP and the SERVER will understand, just the way the MENU is written in a specific language you and the WAITER understand, such that he can place the right order for you at the kitchen. The modern / generally accepted format is JSON { Javascript Object Notation }. The order information { data } will look like this:

//Order_Information 
{ 
   "customerName" : "John Doe", 
   "item" : "MacBook Pro", 
   "price" : 1000 
}

This data is then carried by the API { Messenger } to the Server, which saves the order information and returns a response which the API brings back to the Client. Example response :

//Order_Confirmation
{
   "status": true,
   "message": "Your order has been successfully placed, Kindly
             anticipate delivery in couple days"
}

Upon receipt of this response, the client APP { Web / Mobile } traverses the data to fetch the needed info, most times the message is the only thing the USER of the APP gets to see, others are abstracted. Now you know why i called our guy { API } the messenger.

Why do you need API?

Let’s say you want to display motivational quotes on a section of your web site. You might decide you write all these quotes or copy them off the internet, then save in your database. But don’t forget you need sufficient amount of these, you don’t want to bore your readers with same quotes all the time. So imagine the stress of getting these quotes and save everything in the database and fetch every time, that’s some OVERHEAD right there.

API to the rescue

Here’s API to the rescue, some rather hardworking folks out there have most likely done something similar and were kind enough to make it open to folks like us to reuse. So anytime we need to get quote, we only need to send a request to the API, describing exactly what we want based on the author’s documentation.

API are accessed though endpoints. Endpoints refers to the location of the resources { quotes } on a particular server. So when a request hits the API, it knows just what you want and how to respond to the call.

Take a look at a sample endpoints from talaikis.com :

Endpoints available:

• https://talaikis.com/quotes/random/ — Returns Just one Quote.
• https://talaikis.com/api/quotes/ — Returns 100 random quotes at a time

From the above, call to those endpoints returns different resource. The first returns a random quote everytime it’s called, while the other gives random 100. For our case, I believe the first is just perfect, the user never gets bored!

NOTE: Before you can make use of any API, you have to read the documentation, know what kinds of request it takes, queries and parameters and the structure of the expected response.

A sample request using JQuery.getJSON() ( don’t worry if you don’t understand this, we will cover it in next article ) method to call the first endpoint:

JQuery.getJSON('https://talaikis.com/quotes/random', function(quote){
//code to display your quote on the website goes here.
})

Now let’s take a look at the response below:

{
    "quote": "I'd like to talk about free markets. Information in  
             the computer age is the last genuine free market left 
             on earth except those free markets where indigenous 
             people are still surviving. And that's basically 
             becoming limited.",
    "author": "Russell Means",
    "cat": "age"
}

Does that look familiar? Yea, that’s JSON again. So we got our quote from one call, now you can simply set a timer to make the call multiple times to generate random quote for you.

The above is just one of a thousand reasons you should start using API. I will highlight some below:

• Security - API makes this possible because you get to abstract your project complexity and Database structure hiding some vulnerabilities you might have…
• Partner Connectivity - Imagine you own a huge company that sells airtime to retailers via the internet, you need something to connect you to the numerous customers, that’s API.

There’s a lot more we can do with API, but that’s all we will cover for now. Next article will cover writing and securing our own API.

Summary: API is just a MESSENGER, a middleman between the client APP and the Server { database }.

This link contains list of useful APIs for programmers. Have fun tearing them down.

Read up and Practice More!

Feel free to hit me up for more clarification.