APPLICATION PROGRAMMING INTERFACES - (API)
BACKGROUND INFORMATION ABOUT API
In your small dev journey, it is almost impossible you wouldn't have come across this term somewhere somehow. It crops up so often. So, what are API and what can we do with it. In this article, we would be interacting with some API, and we would use one of them to understand API like in details.
APIs are very useful. For example, Email collector API is very useful if you're building a landing page or a newsletter, preorder, etc. Before this we must understand what are API and what are they useful for.
If you go to yahoo.com, on this page you would notice a section that display the weather parameters of your current location.
If we want to create our own website and we want a module like this, how do we go about this? Notice we wouldn't be able to set up a weather station, take measurement and then integrate this on our site. The problem is that we can't even set up a weather station in all locations of the world.
So where do we get the weather from anyway? We will use weather system interface like weather API.
(https://openweathermap.org/api)
Weather API have collected all these pieces of weather data, do the forecast and all complex stuff, so all we have to do is to use their API to tap into that weather data just like yahoo do it on their page. In the same way too, when you go to tinder [https://tinder.com/] and you see their share friends and shared interest section. Where are these data coming from, its coming from Facebook using the Facebook API. They use those data to populate that section of their site.
Over the internet, we have tones of API that we can use for anything we want to do. In the UK we have police API, that provide data on crimes and other data and people have used it to build interesting stuff. One of this is murdermap. This platform uses the police API to map out murder crimes and classify these crimes based on different metrics especially for London using the data supplied by the API. Someone can use this information to decide where to live and where to avoid.
There are API's that provide prices, and several other stuffs and you can use this data to build anything you want.
WHAT IS API – APPLICATION PROGRAMMING INTERFACES - DEFINED
According to general accepted definition, an API is a set of commands, functions, protocols, and objects that programmers can use to create software or interact with an external system.
What Does This Means?
Let say you go to a restaurant; they will surely have their menu accessible to you but at the same time you can go into the kitchen where we have the ingredients and recipe and probably some surprised chefs. If you go into the kitchen and start eating this raw recipe and ingredients, certainly the restaurant authorities won’t be happy about it. This means that, though there were things they sell that they will allow you to buy but there are other things that are off limit. The same way for websites that takes and have their own data, be it Facebook which has data on users or police API which has data on crimes. There are data they would allow you to access but there are others that they would never want you to see. It is none of your business. So how do these websites tell you what data you can access and how you can access them. If we take the case of a restaurant, they will do it i.e tell you what is available in a menu. The content in the menu may be cakes, cookies, coffee, etc. This is the same for websites. Like OpenWeatherMap, we can have temperature, weather condition, weather image/icon, pressure etc. An API, some people consider to be a contract between a data provider and a developer which says these are data that a data provider provides, the one a developer can use and the ways, protocols and how to use those data and that the website that host this data would not change any of this agreement without a proper notification.
Our definition of an API can now make sense, a set of data programmers/developers can use to create or interact with an external system.
We have seen the ones that allows you to interact with an external system, but we haven't seen any that allow you to create a software. Or have we?
Yes, we have, remember jQuery? (If you want to understand and use jQuery like a pro, kindly contact us or reach out in a mail). It is a tool that gives you access to object and methods that allows you create software easily other than writing vanilla JavaScript to manipulate the DOM.
Let’s take a look at Tindall, on Tindall, Facebook API is used to interact with an external system when you're on their website.
In this article we are going to focus on API that allows you to interact with an external system most importantly an external server. We are going to access some data from some website and we will do that through their API. We will read their documentation to see what we can do with them. We will make requests to their server and get responses all through their API. Their documentation will serve as a menu/guide for what we can do with their data.
API ENDPOINTS, PATHS AND PARAMETERS
In the last few words, we have learnt about API all in the theory. In this section we will be going practical. We will access and use APIs from some website.
When you think about an API you need to be thinking about things like Endpoints, Paths, Parameters and Authentication. These are the four things we will cover and we will see what each of this do.
API ENDPOINTS
Every API that interacts with an external system will surely have endpoints.
Let's quickly look at kanyewest API at kanye.rest for random Kanye West quotes. This data is hosted on kanye west database and one of its endpoints is
GET [https://api.kanye.rest]
Whenever you are using a different API, they would probably have their own endpoints and the details of this will be included in their documentation. Most of the time each use case or functionalities of an API will have an endpoint. If we copy the link above – (endpoint) and paste it in our browser our browser will make a request to the kanye.rest server and that server will send back a response which is a quote by Kanye West.
Let's say we create a website and every day you come to the website; you get a Kanye quote. We can probably do that using this API.
Note: To have the look above, you need to install JSON viewer Pro chrome extension and use it. It helps to view server responses in a more human friendly format. It also has other great options and benefits like finding a specific path and copying of paths. It also has other great functionalities that you might want to try out.
It is important to say that most websites that have API has more data than just a random quote.
In addition to an endpoint, there is also API paths and parameters.
API PATHS AND PARAMETERS
These are things that you can use to narrow down on a specific piece of data from an external server. To illustrate this, we will use an API from a joke website.
[https://sv443.net/jokeapi/v2/]
Through the use of paths and parameters we can narrow down on the kind of jokes we want from this website or server.
Use any of the links above to get to the jokeAPI platform.
This joke API is more complex than the Kanye West one because it has more option for you as the programmer. You can select the kind of joke you want based on category, flags to blacklist, response format, joke type, included string and others. See it below.
The first thing we need to do to use this API is to get the starting point which is the endpoint. If you go to the link above and you scroll down, you will see a bunch of endpoints. You will see one that says GET joke.
If we just copy the URL above and paste it in our browser, you will see that you get an error that says - no matching joke found, no category selected.
So, what is going on here? Although we have the endpoint but there is something missing which is the category. If we use the try it out section,
you will see we have a category call any and it is set to category ‘any’ and if you select programming it changes the URL at the bottom to /programming at the end.
So, the difference here is that we need to select a specific path after the endpoint. If the endpoint is the main tree, the path is the branch.
Here we have seen a path specified here. The endpoint is the main API link and the category is the path e.g programming or dark or any or other ones provided by this jokeAPI.
Remember when we are working with express and building up a server, when we are creating a new path/route we need to plan for it so that when a request is made to our server, we need to be able to catch and filter through to get the specific parameter we want and want to use.
Sometimes we might want to get a piece of data that is specific say a programming joke that contains the word debugging but the API developer won’t probably have thought of this beforehand so in order to allow the API to respond to things like this, we use what we called parameters. These parameters can be attached to the end of the URL after a question mark. It is sometimes a key value pair e.g., /?contain=debugging. The key might contain a string and the query is the debugging which is the value.
It is what is tried out. Other things are added to the link as we select some options in this section. The more we change the default selections, the more the parameters that are added to the link. Now notice if we have more than one query, the first query follows after the question mark, and the subsequent queries follows after the & symbol.
When you want to specify a parameter, remember that you need these symbols to use them, it comes after a question mark (?), then the key, then followed by an equal to (=) sign, then followed by a search string. Any other parameter or key value pair which is an additional query will come after the and (&) sign.
If we use this link in our browser, we will get a joke with the options we have specified.
[https://v2.jokeapi.dev/joke/Programming?blacklistFlags=sexist&type=single&contains=debugging]
Note: You can select plain text under the response format to add that parameter and your responses would be in plain text.
Now with the addition of a parameter, we are able to get something specific and a precise thing that we want.
Now, you have seen an API in action, how to use an endpoint, also how to identify and use path and parameters to narrowed down on a piece of data.
You can stop reading for now. Take some time and play with this API adding some path and parameter in your browser and making some requests and getting responses. Ensure you know what is going on when you type out those long URLs in your browser.
In the next article we will talk about authentication and what we will have in our responses.
Don’t forget to drop your comments, suggestions and any questions you might have.
Top comments (0)