What is REST API

Rep­re­sen­ta­tion­al state trans­fer (REST) is an archi­tec­tur­al style designed to take advan­tage of exist­ing pro­to­cols like HTTP/HTTPS. REST defines a set of con­straints to be used for cre­at­ing APIs. When an API is designed based on the prin­ci­ples which adheres to the Rep­re­sen­ta­tion­al state trans­fer archi­tec­tur­al style it is called a REST­ful API. Unlike SOAP ser­vices, REST­ful APIs are not con­strained to one par­tic­u­lar data type like XML. Instead, REST­ful APIs can return any type of data for­mat like JSON, YAML, XML, TEXT etc depend­ing on the client request. Also the datatype is inde­pen­dent of the meth­ods and resources.

REST was designed by Roy Field­ing in his 2000 PhD dis­ser­ta­tion ​“Archi­tec­tur­al Styles and the Design of Net­work-based Soft­ware Architectures”.

Through­out the HTTP stan­dard­iza­tion process, I was called on to defend the design choic­es of the Web. That is an extreme­ly dif­fi­cult thing to do with­in a process that accepts pro­pos­als from any­one on a top­ic that was rapid­ly becom­ing the cen­ter of an entire indus­try. I had com­ments from well over 500 devel­op­ers, many of whom were dis­tin­guished engi­neers with decades of expe­ri­ence, and I had to explain every­thing from the most abstract notions of Web inter­ac­tion to the finest details of HTTP syn­tax. That process honed my mod­el down to a core set of prin­ci­ples, prop­er­ties, and con­straints that are now called REST.

One of the key advan­tages of REST APIs is that they are flex­i­ble. Datatype is not tied to resources or meth­ods. This kind of flex­i­bil­i­ty allows devel­op­ers to design an API that meets diverse requirements.

Under­stand­ing REST API Design #

A REST­ful sys­tem is based on 6 guid­ing con­straint. Most of the REST­ful APIs do not fol­low the REST require­ments and con­straints set by Dr. Roy Field­ing. It’s impor­tant to under­stand what makes a REST API REST­ful, and why these con­straints exist before build­ing your API. Lets look into the six prin­ci­cles which makes an API RESTful.

• Client-Serv­er
• State­less
• Cache
• Uni­form Interface
• Lay­ered System
• Code on Demand

Client-Serv­er: #

The Client-Serv­er con­straint con­cept is seper­a­tion of con­cern. This means that the client and the serv­er is decou­pled and inde­pen­dent of each oth­er and any changes made to client or the serv­er does not impact the oth­er. This con­straint allows the client and the serv­er to grow and scale inde­pen­dent of each other.

State­less: #

The request-response between client-serv­er is state­less which means there is no data stored on the serv­er side to deter­mince the action of the request call. Each request made is inde­pen­dent of one anoth­er, and each call con­tains all of the data nec­es­sary to com­plete the request suc­cess­ful­ly. This con­straint improves APIs reli­a­bil­i­ty by not stor­ing the state. If nec­es­sary the ses­sion state is stored on the client side.

Cache: #

The Cache con­straint par­tial­ly or com­plete­ly elim­i­nates the client-serv­er inter­ac­tion by caching the response. Due to the State­less con­straint, the serv­er will be bom­bard­ed with too many requests even if the response does not change. By imple­ment­ing cache, the requests to the serv­er is reduced. The response should always be defined cacheable or non-cacheable and if it is cacheable then cache expiry time should be pro­vid­ed. Caching improves scal­a­bil­i­ty and per­for­mance of an API.

Uni­form Inter­face: #

The uni­form Inter­face con­straint is fun­da­men­tal in design­ing any REST­ful archi­tec­ture. This con­straint decou­ples the sys­tems involved in the archi­tec­ture and makes it eas­i­er for the sys­tems to scale inde­pen­dent­ly. There are 4 con­straints to the uni­form inter­face which are:

Resource iden­ti­fi­ca­tion in requests: #

Each resource are iden­ti­fied indi­vid­u­al­ly in the request which are iden­ti­fied using Uni­form Resource Iden­ti­fi­er (URI) para­me­ter in the request URL. The resources data rep­re­sen­ta­tion or the data for­mat is inde­pen­dent of what is sent to a client as a response. For exam­ple, a mobile client can make a request to get a recource in the JSON rep­re­sen­ta­tion while anoth­er web client can make a request to get the resource in XML representation.

Resource manip­u­la­tion through rep­re­sen­ta­tions: #

HTML, XML, JSON, PNG, etc for­mats are rep­re­sen­ta­tions of the iden­ti­fied resource. REST­ful appli­ca­tions may sup­port dif­fer­ent rep­re­sen­ta­tion of the same resource under the same URI by allow­ing clients to indi­cate which rep­re­sen­ta­tion of a resource they wish to receive via the Accept HTTP head­er para­me­ter. Resources can be updat­ed (or cre­at­ed) by send­ing rep­re­sen­ta­tions from the client to the serv­er. REST­ful appli­ca­tions may sup­port more than one rep­re­sen­ta­tion for updates to the same resource.

Self-descrip­tive mes­sages: #

All client-request and the serv­er response is a mes­sage. Each mes­sage includes con­tains all the infor­ma­tion nec­es­sary to describe how to process the message.

Hyper­me­dia as the engine of appli­ca­tion state (HATEOAS): #

To sim­ply put, with HATEOAS con­straint the serv­er response con­tains hyper­me­dia links for fur­ther action on the resource. This is the mag­ic of REST­ful API.

Lay­ered sys­tem: #

The lay­ered sys­tem archi­tec­ture con­sists of dif­fer­ent lay­ers ^such as proxy layser, secu­ri­ty lay­er, etc. This also makes it easy to scale the sys­tem lay­ers inde­pen­dent of each other.

Code on demand: #

This is the only OPTION­AL con­straint in the REST archi­tec­tur­al design. REST allows client func­tion­al­i­ty to be extend­ed by send­ing code in the form of applets or scripts via a response. This sim­pli­fies clients by reduc­ing the num­ber of fea­tures required to be pre-implemented.

Richard­son Matu­ri­ty Mod­el: #

API matu­ri­ty lev­el is deter­mined using the Richard­son Matu­ri­ty Mod­el. Learn more about Richard­son Matu­ri­ty Mod­el (RMM)