Client Server Communication: RESTful API

Application Programming Interfaces or API’s for short are a cornerstone of the World Wide Web. As a current student of Software Development, I’ve decided to dive into the world on trying to simplify what it means to create/build an API and more specifically, the building of a RESTful API.

During a recent retrospective, a question was asked about eating at a restaurant. Restaurant interactions happens to be a great example of an API.

As a customer, you are looking at the provided menu and deciding what it is you would like to eat. When you provide the order to the waiter (usually I would use the term server, but in this context, I did not want to make things more confusing) “I’d like a Phorrito (Pho/Burrito) with a side of chips” The waiter will head to the POS, type in the order to be processed and send to the Kitchen (in this case our server). Once the request is made, the waiter picks up the resource from the server and brings back the order to the table for the Client to enjoy. There you have it, an API and a Phorrito!

RESTful

There are different ways of building an API for consumption, but the most prevalent and diverse creation today is a RESTful API. What we are doing is developing the architecture of our API in a way that can communicate with multiple and different request languages or methods. It will rely, for the most part, on stateless, client-server protocol, and almost always use HTTP.

In a PhD thesis written by Roy Fielding, he defined the Representational State Transfer (REST) architectural styles. In the paper he points out guiding constraints to define a RESTful system that we will discuss below.

Client-Server Architecture

The restaurant scenario mentioned earlier is an example of client-server architecture. The separation of client and server makes it so each can scale or improve individually and neither is dependent on each other. The fact that the restaurant wanted to create new dishes, does not depend on any input from the client and if the client wanted to add 3 people to the table, the inputs to the kitchen would not be affected (disregarding load management in this scenario).

Statelessness

Within each of the requests to the server will request all of the necessary information relevant to the request, whereby the server does not store any of the request information. The session state is kept with the client. The kitchen does not have to remember any specific order from a customer but will build according to how it is given to them via the waiter. If the customer wishes to add on some onion rings, a new request will come in and the customers state will update, but has no affect on the kitchen state.

Cacheability

To help improve scalability and performance, clients can store responses for future use. In our restaurant example, if a customer comes in multiple times, the waiter can possibly skip most of the interaction and send the request to the kitchen before any interaction with the customer based on their cached memory of previous repeated orders.

Layered System

The client side should work as intended no mater if there are intermediaries between the communication to the end server. These proxies or load balancers should not affect the communication and there would be no need to update client code. When I worked in a kitchen as a grill cook, part of my job was to hold orders in batches until I felt the line was ready for more. In effect I was load balancing. This had no affect on what the customers were ordering and did not disrupt the client end server communication chain.

Uniform Interface:

The setting of standards and global concepts so that all of the web can talk with each other. This is fundamental to the design of any RESTful system. With any number of restaurant, the menus and dishes will be different, but the process of receiving an order putting into the POS for the kitchen to make and bringing to the table will be universal.

Resource identification in request

The use of the Uniform Resource Identifiers (URI) is standard to identify a resource

Resource manipulation through representations

The use of the Defined HTTP standard methods

Self-descriptive messages

Defining the use of a MIME (Multipurpose Internet Mail Extension) media

type application/json 
text/xml

Hypermedia as the engine of application state

To make it so the user can navigate the API using Hypertext links rather than know the specific URI

http://api.mainsite.com/collection
http://api.mainsite.com/collection/users
http://api.mainsite.com/collection/users/favcolor
http://api.mainsite.com/collection/users/favcolor/greenforest.jpg

Conclusion

This is only the basics of understanding the RESTful API. Once you can apply these practices you will be able to create amazing applications that will be accessible to billions of people.