An Overview of APIs and REST

An API, also known as an Application Programming Interface, is essentially as it sounds— an interface used by programmers for their application. To be more specific, it is an interface for the application to communicate with a server. This interface is actually a part of a server (back end) that handles requests by a client (front end).

Many companies, like Google, have different APIs offered for the many services that they offer. These APIs are often used internally or for customers. For example, Google has a downloadable Maps app that directly accesses the Maps API. It only needs raw maps data from the server for it to function, whereas a web browser accessing the Maps website will need HTML from the server in addition to maps data to build the entire GUI. The app already has everything it needs for the GUI built-in.

As for an example of customer use— most cell phone carriers provide a map on their website to show the areas that their towers provide coverage to. Instead of developing an entire maps system for this to happen, they may choose to use Google Maps API.

What is a RESTful API?

REpresentational State Transfer is a specific type of API architecture that we will be going over in this blog. A couple of key things to note about REST is that it is intended for use with HTTP which, as you may know, is already very widely adopted, and it is stateless. Stateless just means that each request made to the server is intended to contain all of the information required by the server to fulfill said request. So, for this request, we will likely need a few basic things.

• An endpoint - a location to access the server in the form of a specific URL

• An HTTP Verb - an operation to request of the server

• A callback - a function which dictates how the data that comes back from the server will initially be handled in our application

With REST, we would typically use the methods specific to HTTP. The four most common methods/verbs are:

• GET
• POST
• PUT
• DELETE

There are many ways to use REST and many languages that it is supported in. For my demonstration, I will be using JavaScript's built-in Fetch API to go over GET and POST, since they are the most common of the four I just mentioned.

GET

fetch('http://domain.com/api')
  .then(response => response.json())
  .then(data => console.log(data));

In the above example on the first line, we have an endpoint URL to point to the data we want to 'get'. On the second and third lines, the data is then being converted from an HTTP response to JSON data, and then that data is being logged to the console. Depending on your endpoint URL, that data you get back might be an object or possibly an array. The third line is where you could place a callback of your own to do whatever you would like with that data, rather than log it to the console. Notice that the method type is never specified. This is simply because the JavaScript Fetch API by default assumes a GET request and the example is to demonstrate the simplest use case possible.

POST

fetch('http://domain.com/api', { 
    method: "POST", 
    body: JSON.stringify({ 
        username: "username", 
        password: "password", 
        id: 3
    }), 
    headers: { 
        "Content-type": "application/json; charset=UTF-8"
    } 
}) 
.then(response => response.json()) 
.then(data => console.log(data)); 

In this example, we can see that 'fetch' is taking a second argument of an object. This object specifies the type of request it is making to the server (POST), provides an object in the form of a string using JSON.stringify(), and specifies that data type in the 'header' property. This could be used to either submit data that will be saved to the server or to submit data that the server will process and then send something back. Referring back to the Google Maps example, you could imagine submitting a zip code in a POST request and then the Google Maps API returning a location to display on the map.

Conclusion

RESTful APIs can be very useful for their flexibility and scalability. REST is also very widely used across the web and is considered easier to use than alternatives like SOAP. REST has been growing rapidly in recent years, and in 2017, a massive API directory ProgrammableWeb reported over 80% of its profiles used REST architecture. So I think it would be safe to say that REST is an important and useful type of API to know about!