Understanding the RESTful API
Tags: API, Rest, Rest Api

API’s are pretty much everywhere, whether you are aware of their use or not. API is an acronym that stands for Application Programming Interface. The application portion is any software separate of other components. For example, the chrome browser is an application but can have other applications within, the browser extensions. You can plainly separate the browser extensions used by Chrome, such as an ad blocker or VPN as an individual, to identify each as an application. The API is the software go-between that allows these applications to talk to each other. Sort of like when you had two friends who weren’t talking to each other and you had to relay the messages between them. In Google Chrome, a common instance of utilizing an API is a weather application. To get the relevant data for the weather, the application requests the latest weather details for a particular area. The API uses the request to gather up the data and it is reformatted in a way that the application can use. Maybe the application made a request using a language or format that the server could not recognize. The API can reformat this request for consumption at the server, then reformat again for consumption at the client side. When I talk about consuming the data, I mean the data is understandable and can be used.

The best analogy, in my opinion is the waiter at a restaurant. The customer orders something from the menu, the waiter (the API) returns to the kitchen (the server) and obtains the order to return to the customer. I think that is the simplest way to look at it. Maybe the customer didn’t speak the kitchen’s language, so the server had to work as a translator to relay the order.

API’s can also function as a layer of security. An API can control access to parts of an application or limits the amount of information being shared by both sides. You don’t want your whole smart phone to be accessible to an application. Instead it can limit what is seen by the application by sending packets of data that are necessary. Let’s say you were at a restaurant and you order a milkshake. The waiter will return to the kitchen and request the milkshake. The kitchen requests that you provide a flavor and maybe a certain coupon that allows you to make the order; the waiter returns to the table to ask your flavor, takes the coupon and returns to the kitchen again. The waiter then returns to your table with the vanilla milk shake you ordered with a crazy straw and two cherries on top, just as you ordered.

There are many different reasons API’s are used among the examples provided above. Modern API’s have standards, usually HTTP and REST, that make the use of API’s accessible, efficient and a huge time saver for many developers.

Before we talk about REST API’s let’s touch on HTTP requests and responses. Most of the following is applicable to all API’s. When you are using an application, it will make a request to some remote server. The request is a text document that contains three parts. The first is a verb for what action is being requested. A REST API uses GET, POST, PUT, DELETE, HEAD, OPTIONS and PATCH. We will talk more about these verbs in just a bit. The next part is a header, which is information about the request and the third part is the content. The header allows the client and server to pass on additional information. Perhaps an HTTP request is conditional and you want certain information if the statement in the header turns out to be true. I like to think of the header as the part where you can make a distinction. For instance, when we ordered that milkshake in the restaurant, the request given to the waiter contains a header which could have said if the coupon was printed from Groupon, we could have the glass extra large with our crazy straw and an extra cherry. The content, which is optional, is just that, in this case, just our fancy milkshake.

It is important to note that the request and the response are two different actions. There is not a constant connection between the client and server. The request is sent to the server and the response is given by the server in return. It is important because you can adjust the amount information that is requested, or the time involved. When you adjust or scale these requests, you can optimize the performance of the application. Let’s say the kitchen has a bunch of orders and many waiters were lining up and the output of the kitchen was slowing down, this can be optimized in many different ways. I can make another article about that soon.

The response is also a kind of textual document. It also returns three parts. The first part is the status code. The first number in the status code is any number between 1 and 5 each indicating a specific class of responses. You should check them out here. The next part is any headers that are useful to you, again the distinctions that can be made, and lastly the content that the server sends back in its response.

What is a REST API?

REST is an acronym that stands for Representational State Transfer. This is a particular architecture for an API that uses HTTP requests to consume the data. A REST or RESTful API are the same thing; RESTful is used to indicate that it conforms to the standards for a REST API. There are six standards or constraints for an API to be Restful and are fundamental to its design.

1. Uniform Interface: A uniform interface allows the client to talk to the server in a single, constant language. Think of a global standard for a huge network that enables everyone to understand each other. The uniform interface is obtained through a single URI/URL and uses those verbs mentioned above. The URI identifies the resource. Think of it as the string of characters I used from the menu to order (GET) the milkshake. The waiter requires each message to include precise information that describes the order (process) requested from the kitchen.

2. Client-Server based: The client and the server are separate and independent of each other. Uniform Interface and requests are the responsibilities of the client; Data access, workload management and security are the responsibilities for the server. Essentially, the customer at the table needs to ensure that the request has the valid information for the order. The kitchen has many other things to worry about besides making sure one customer has access. The kitchen is managing its workload. In other words, it is ensuring that all orders are quickly and efficiently reaching the mouths of their customers. The separation of the client and server allows for this optimization.

3. Stateless: Ultimately when a request is received by the server, it will send its response and the server will not have any memory of that action. It will forget all about you. The amount of time a client is connected to a server using a REST API are short and enables the server to receive many requests. The computational limits of memory and disk can max out if the server had to wait around for the client to send another request. Think of the kitchen stopping each time they had to send the waiter back to a table. When there are multiple tables to deliver orders to, the kitchen would take way too long and the people at the tables would probably leave to go to another faster restaurant; same goes for an application.

4. RESTful resource caching: A response should be defined as cacheable or not; because REST API’s are designed for huge workloads, it is recommended that a temporary storage is available to maximize efficiency of delivering responses.

5. Layered system: Similar to caching the design is based on optimization and allows many different layers of servers to work together to deliver the most efficient results. A client could be communicating with the actual server, a proxy or another intermediary, it doesn’t matter, the relative response is still delivered.

6. Code on demand (Optional): Usually, a server sends back some static files like HTML or JSON but it is possible for the server to send back some executable code. It is not a well-known standard of REST API’s and not used often. It is cool to think about where this concept can take things. I am definitely going to explore some smart REST API’s in the near future.

Any language that can make an HTTP request can use a REST API thanks to the uniform interface. Using the HTTP methods or verbs, we can make requests for different actions that we require of the server. The most common verb used in a request is GET. In order to GET the data we want to obtain, we have to use an endpoint URL. An endpoint is the location at which the API can access the resources needed. For example, an application could use https://domainname/user/post_id?format=json as an endpoint for the GET method while delete endpoint can be https://domainname/user/post_id/delete_post as an endpoint to execute a delete. The following table describes the actions associated with the method.

HEAD, which is similar to the GET method only returns the headers, and OPTIONS, which returns supported HTTP methods, are not used very often but is always good to know available options. HTTP methods can use the same URL and differ given the verb. A POST request to https://domainname/user/67 creates the user with the ID of 67 while a PUT request to https://domainname/user/67 updates the user 67 with data located in the content part of the request.

The next part of a request are the headers and this contains valuable metadata of the request. These are important in a Restful API request and the amount of available headers is large; you can even define your own header if needed. Among the many headers available you should be aware of these common header values:

Authorization: Carries credentials containing the authentication information of the client for the resource being requested.

WWW-Authenticate: This is sent by the server if it needs a form of authentication before it can respond with the actual resource being requested. Often sent along with a response code of 401, which means ‘unauthorized’.

Content Length: Indicates the size of the content and depends on what verb was used in the request.

Accept-Charset: This is a header which is set with the request and tells the server about which character sets are acceptable by the client.

Content-Type: Indicates the media type (text/html or text/JSON) of the response sent to the client by the server, this will help the client in processing the response body correctly.

Cache-Control: This is the cache policy defined by the server for this response, a cached response can be stored by the client and re-used till the time defined by the Cache-Control header.

The last part of the request is the content, also known as the body. The content can have HTML, CSS, JavaScript, XML, JSON; as you can see, it can be anything. Content isn’t valid when using some verbs. For example, GET will never have a content body on a request because all you are doing is requesting that the server returns some desired information.

Now that you have an understanding API’s and what makes an API RESTful, we can begin to utilize them. There are a number of different tools we could use and a lot more articles can be made regarding each one of those tools so stay tuned for some more follow-up articles regarding the use of REST API’s, especially for smart REST API’s.