APIs in Javascript

When looking into APIs for the first time, it was difficult to grasp a general understanding of what an API is as how it can be used. For starters, the acronym definition made things even more confusing for me and I can understand why someone would stop there and never turn back.

API — Application programming interface.

I don’t think i’ve ever seen 3 words seem more unclear together. Most simply put, an API is used as a standard way to exchange information between different things. A software company releases its API to the public so that other software developers can design products that are powered by its service. Think of one of your favorite songs that has a featured artist in it. That artist was interested in collaborating with that specific artist with the intent of enhancing their music. As developers we are constantly looking for opportunities to enhance our applications with the intent of making the a great experience for our users. We will look at an simple example API below using javascript along with the jQuery library. We will be looking at the GIPHY API. Imagine you have a web app and within your app you’d like to be able to search by keyword for a funny gif. GIPHY has provided to developers the tools needed to accomplish such a task. Let’s think about what we are doing in the process of creating this feature. We discovered an existing software that has a feature we think our web app can benefit from by integrating with it.

Step 1. API Documentation!

You just bought your brand new ikea dinning room table and it is time to get it up and standing on all four legs. You won’t get anywhere without reading the included 25 pages of instructions. Just like your new table, an API comes with a very structured set of instructions designed and documented by the creators of that software themselves. When using an API, there’s no room for a loose screw that you might be able to get away with when building your table. An API documentation is not a guideline, nor a template for you to build on. It is a strict set of instructions you must follow in order to have the API cooperate as desired. Like most different manufacturers selling tables out there, all APIs have unique documentation that must be followed precisely. Sometimes this documentation may be more unclear for one than it was for another. After looking into all the resources that software has provided, some further research may be required if things are still unclear. Google tends to solve any further confusion. You can’t be the only person trying to utilize that API.

Let’s look at the documentation of the GIPHY api we are looking to use: https://developers.giphy.com/docs/

For this example in particular, it looks like we need a “API key” to get started with GIPHY. This can easily be obtained by signing up for a free developers account with them!

Let’s see what’s written for us in this documentation and based on what we see, let’s figure out which pieces we will need to to build out our feature in our web app!

I think this is what we’d like to use. Search for a gif by keyword! That would be perfect. But what does all this mean? Well when utilizing an API, we will be sending an HTTP request to the server such as a GET or POST request. For our example, we are GET-ting gif from GIPHY which is why this will be a GET request. We are looking to receive information from our server and use it in some way. When the time comes and we receive the information we are requesting, it will be sent in JSON format. JSON stands for Javascript Object Notation. It is essentially a large object with key/value pairs with all the information crammed in. We will shortly see how somewhere inside the JSON object we receive will be the links to the gifs we requested!

What other instructions do we have at our Endpoint above (Endpoint is the destination we are looking to receive or send information to/from). HOST is where we will be requesting our information from and PATH narrows down the task we are looking to accomplish. Similar to a mailing address, think of the HOST as the City/State and the PATH as the unique address. 
Now that we have our HOST and the unique PATH to request information from, lets put them together. We will be requesting information via a GET request from:

http://api.giphy.com/v1/gifs/search

Sounds pretty good so far, but as you may have noticed, our url says we are requesting information via a search but doesn’t say what we are searching for! I want gifs of kittens so lets make sure to mention that to the server!

Luckily we have our documentation to teach us how to request what we are looking for using parameters:

This is pretty cool. Our url http://api.giphy.com/v1/gifs/search can accept different parameters after the /search to help us customize our search. It looks like there are two required parameters in our example that we need to include, so lets just worry about those two for now. When adding parameters to the end of your url, they must be in a specific format in order for the request to understand what we are asking for. Parameters are added using a ‘?’ but if you have multiple parameters to add, the first parameter will be added using a ‘?’ and any parameters that follow will use a ‘&’. Let’s see what that looks like in our example. We need to add the search term or phrase along with our API key we now have after signing up. The documentation mentions that our phrase will be added using the q variable and our API key will be added using the api_key variable. Still wanting to see gifs of kittens, our url should now look like this:

http://api.giphy.com/v1/gifs/search?q=kittens&api_key=5e43d3b89ae74dd5931c27cce50d5f6e

Notice the ? before our first q parameter and the & before our second api_key parameter. Now our request should understand exactly what we want and we are granted permission for our request using our API key!

The only thing left for us to do make the request in our javascript application. To do this, we will be using ajax, provided to us by the jQuery library. We have simple index.js and index.html files ready to get us started. In our index.js file, we will be working directly in our document ready.

So how does ajax work? Ajax is pretty cool. We will be calling the ajax method from jQuery using the following notation:

$.ajax( { } )

ajax takes in a object as an argument. This object will include our url that we are making a request to along with and any ajax settings we are providing to configure the request. Like all javascript objects, the url and any settings will be sent in a key value pair notation. jQuery provides many different settings that can be used to configure the request. For our example, we will only be using url, method, and success. Feel free to check out the jQuery documentation for information on all the settings available: http://api.jquery.com/jquery.ajax/

Let’s fill in our request a little more.

$.ajax( { url: , method: , success: ,

} )

url will just be a string value with our full url:

$.ajax( {

url: ‘http://api.giphy.com/v1/gifs/search? q=kittens&api_key=5e43d3b89ae74dd5931c27cce50d5f6e’,
method: ,
success: ,

} )

method will be the type of HTTP request we are making. We mentioned it being a GET because we are requesting data from the interface (also wrapped in a string):

$.ajax( {

url: http://api.giphy.com/v1/gifs/search?q=kittens&api_key=5e43d3b89ae74dd5931c27cce50d5f6e’,

method: ‘GET’ ,
success: ,

} )

success will be how we use the data we receive! For our example, lets just get all the gifs to display in the body of our index.html. The value for success will be a function that takes one parameter which will be our requested data if the request was successful. That data should be our JSON object. But how do we know what is in that data in order for us to navigate to the appropriate keys to get the data we are looking for? One way is to take our url we are using to make a request and just copy and paste it into our browsers address bar. That will display to us what that object looks like and all the key value pairs nested within. It may look a little messy. There are Chrome extensions and softwares available such as Postman which can help clean that view up for you. When we look at our object we will see that there are 25 objects within our object! This is because the Search Endpoint defaults to providing 25 gifs for us (unless otherwise configured in the url parameters). There is a key nested in each of our 25 gif objects called images: which contains all the gif url’s (contains different fixed sizes for small or larger use). We will iterate all 25 objects and append that url to our index.html body! On each object we will need to map through:

gif >> images >> fixed_height >> url

in order to get the desired image appended to our body. Let’s add this function as a value to our success key in our ajax request:

$( document ).ready( function(){

$.ajax({ url: ‘http://api.giphy.com/v1/gifs/search?q=kittens&api_key=5e43d3b89ae74dd5931c27cce50d5f6e’,

method: ‘GET’,

success: function(giphy){

giphy.data.forEach(function(gif){

$(‘body’).append(`<img src=’${gif.images.fixed_height.url}’>`)

})

}

})

})

Save and open index.html in your browser and you should see 25 gif of kittens!!

The fun part about watching the magic happen and getting your request to run successfully is customizing the way you view and request the data. For example, we don’t want to just see kittens in our app right? I mean, you might. But what you can do is create a simple form in your index.html and take in the string that was entered. You can take that string of a keyword or phrase and interpolate it into you url request! How cool is that? Making your new API integration dynamic within your application!

The best way to learn more on how to use API’s and understand their use is to play with more of them. Think of some of your favorite websites and look up their API documentation and the cool things they allow you to do with it!