loading...

It's time to give a gleeful eye at RESTful APIs.

michael_bazile profile image xoweekday Updated on ・6 min read

Hi there, how are you doing? If by chance you decided to click on this link that must mean you're here to learn about RESTful APIs. Hopefully after reading this blog will you accomplish that. Let's not waste any more time and get straight into it shall we?

Let's start off from the beginning, what exactly is an API? Great question. An API is actually an acronym that stands for application programming interface. That's just a really fancy way of describing how two different pieces of software can communicate with each other. It's probably unbeknownst to many people that they actually interact with a variety of different APIs every single day.

Let's take the music discovery app Shazam for example. The Shazam app is an app that will identify any song that you do not recognize by simply pressing a button and holding your device close enough to the music. This is an extremely powerful tool to have and all we, the user, have to do is just press one button to use it. We do not need to know how or what happens behind the scenes, we just download Shazam, follow their steps to login and voila! Next time you and your friends are in the mall and you can't remember the name of the song playing, you just pull out your phone and hit a button.

That, my friends, right there, is an example of an API at work. In this case, the user (you and I), goes to Shazam, hits a button, then something happens in the background, and in return we get information from Shazam indicating the song that is currently playing. That's the beauty of APIs in a nutshell. They hide the abstraction of the how and why, in return all you need to know is how to access them and they will make life so much easier.

Now that we know what APIs are, let's dive into a specific type of API. The one you came here for, and that is RESTful APIs. REST is another acronym that stands for Representational State Transfer. The originator of this architectural style is Roy Fielding. If you want to learn more about him here's a link to his dissertation on REST.

Up until Roy Fielding came out with REST, there was not really a universally accepted way to go about designing APIs. So it was really difficult to go about accessing other developer's APIs because each API came with its own set of rules of how to access them. Thinking back to the Shazam app, signing up to use their app isn't very difficult. Just imagine if every app had drastically different ways to go about logging in, that would make the user experience every frustrating.

The same goes for developers trying to access APIs to use in their application. In comes RESTful APIs. The ideology behind RESTful APIs is that any API designed with REST in mind will make it easier for other developers to access and use them since mostly all RESTful APIs have the same characteristics. So when a developer comes across a RESTful API, that developer will know what to expect when trying to access information.

Pretty neat right? Now that we covered what APIs are, and we dug into what RESTful APIs are, how about we get into how we would actually go about accessing one of these wonderful RESTful APIs that are just out there waiting to get used. Not sure if you've ever heard of this application before, but you and I are going to get information an API from this thing called YouTube.

search = (query) => {
      $http({
        method: 'GET',
        url: 'https://www.googleapis.com/youtube/v3/search',
        params: {
          part: 'snippet',
          q: query,
          key: YOUTUBE_API_KEY,
          maxResults: 5,
          type: 'video',
          videoEmbeddable: true
        }
      }).then(function successCallback(response) {
        console.log('success', response);
      }, function errorCallback(response) {
        response.error.errors.forEach(function (err) {
          console.error(err.message);
        });
      });
    };

The more you research into APIs, you'll find that there are many different ways to go about interacting with APIs. The code snippet above is an AngularJS HTTP GET request that is going to request information from the url provided in hopes that we can get information back from YouTube's API to use in our app. Please, do not worry if that code seems daunting, we are about to go over exactly what it's all doing in a moment. First I want to give you some helpful insight on a few concepts before then.

Here comes another acronym. HTTP. This acronym stands for hyper text transfer protocol. When I first learned of this concept it flew clean over my head and went who knows where. However, after breaking down the acronym into smaller parts it started to make more sense as to what it means. The main thing I want you to get from that is the last two words. Transfer Protocol. As the name implies, in order to access a RESTful API you must follow proper protocol that is specified by the developer(s) who made that API.

So an HTTP GET request is one of five different methods that you can implement in your code when consuming RESTful APIs. It depends on what your particular task is, but generally you'll mainly be using GET request to retrieve information from the API of your choice. In this case it's YouTube's API, and you must specify exactly what kind of request you intend to send to it.

Okay, how are you doing? I know it's a lot of information, but I mean you already know this much more already. Take moment, its cool, I'm not going anywhere. Once you've come back we'll get right back to it.

url: 'https://www.googleapis.com/youtube/v3/search',

The next thing is the url from above, this url will act as directions from the request from our computer to the API that we intend to access. With /search being our endpoint. An endpoint is the point at which the two pieces of software will communicate. Two pieces of software being our request from the code snippet above, to YouTube's API. Specifically their search API, because that is the endpoint that we specified in the url.

Nice! We have everything pretty much in place, we have our HTTP request, we have specified the type of HTTP request we want to send, we have the location we want to send our HTTP request, not finished yet though. Just a few more things to cover.

params: {
          part: 'snippet',
          q: query,
          key: YOUTUBE_API_KEY,
          maxResults: 5,
          type: 'video',
          videoEmbeddable: true
        }

The params above are specific to YouTube's API, in the way that how you must format your request. Going back to the Shazam app, you must follow certain steps before you can have access to what the app can offer. The same goes for APIs. This will vary from API to API,so it's important to go lookup the documentation for whichever API you plan on using.

.then(function successCallback(response) {
        console.log('success', response);
      }, function errorCallback(response) {
        response.error.errors.forEach(function (err) {
          console.error(err.message);
        });
      });

Lastly, once you've sent the request you will either receive the information you requested for, or you'll get an error message indicating what went wrong with the request. If you do get an error message, it's best to google what the error message is and refactor your request from there. Other than that, we did it! We sent an HTTP request to YouTube's API and got information back from it. It's time to play The Weeknd's new album all day now!

So in conclusion, we've learned what APIs are. We learned what RESTful APIs are. We learned how to make an HTTP request to a RESTful API to get information to use in our application. Fantastic! Good work. I really hope you've gained something from reading this post, so you can now go out in the world and gleefully eye other RESTful APIs!

Posted on by:

Discussion

markdown guide