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

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, you will accomplish that. Let's not waste any more time and get straight into it, shall we?

Let's start from the beginning. What exactly is an API? Great question. An API is an acronym that stands for an application programming interface. That's just a 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 simply download Shazam, follow their steps to log in, 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 open Shazam, and press a button.

That, my friends, is an example of an API at work. In this case, the user (you and I), goes to Shazam, hits a button, 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, and in return, all you need to know is how to access them.

Now that we know what APIs are let's dive into a specific type of API. The one you came here for, and 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 a universally accepted way to go about designing APIs. So it was really difficult to go about accessing other developers' 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 you have on your phone has drastically different ways to go about logging in and using them. That would make the user experience very frustrating and confusing.

The same goes for developers trying to access APIs to use in their applications. 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 consume 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 accessing information.

Pretty neat, right? Now that we covered what APIs are, and we've dug into what RESTful APIs are, how about we get into how to go about accessing one of these wonderful RESTful APIs?

I'm not sure if you've ever heard of this application before, but you and I will consume information via an API from this thing called YouTube.

const 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 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 data 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 precisely what it's all doing in a moment. First, I want to give you some helpful insight into a few concepts before then.

Here comes another acronym. HTTP. This acronym stands for hypertext 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 components, it started to make more sense as to what it meant.

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 the proper protocol that is specified by the developer(s) who built 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 your particular task, but generally, you'll mainly be using GET requests to retrieve information from the API of your choice. In this case, it's YouTube's API, and you must specify exactly what method 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 a moment, it's 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 method of HTTP request we want to send, and we have the location we want to send our HTTP request. Not finished yet. 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. Going back to the Shazam app, you must follow specific steps before you can access what the app has to offer. The same goes for APIs. This will vary from API to API, so it's vital to 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'll either receive the information you requested or an error message indicating what went wrong with the request. If you get an error message, it's best to google the error message 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 consume information that we can in turn then use in our application. Fantastic! Good work. I hope you've gained something from reading this post, so you can now go out in the world and gleefully eye other RESTful APIs!

Comments

[Nasasira]

Thanks for the insightful article
The emphasis on unified interfaces between components is a core feature that sets the REST architectural style apart from other web-based styles.
If interested in digging deeper, check out How an API Gateway Empowers RESTful API