What is a Rest API?

Surprisingly I keep answering this question over and over. I think the first time I wrote a definition online in a forum was 10 years ago. I am still seeing the question everywhere and it’s not unusual to answer it at work several times. So I decided to add a quick summary here, one more time.

Let’s analyze every part individually. REST is Representational Web Transfer, basically, the web. As you probably now the principles of REST are simple and it could be summarized like this:

Connect to the server Give a VERB and a path to an URI Obtain an answer It’s surprising how many things you can do with such a simple schema. To consume websites you only need one (or two) verbs. GET to obtain data and POST to send data. The POST used in many web forms is not the one we use for APIs and it’s called “overloaded post”.

RESTful refers to a full implementation of the verbs and in general doesn’t make too much sense if you don’t add “ROA” to the end (Resource Oriented Architecture). Without the ROA part, using the verbs is not accurate enough and in general tend to represent different concepts like SOAP which is mainly RPC calls using an envelope. Most of the time you will find RPC or hybrid REST services that are only calls to methods that do a lot of things internally.

Even when RESTful is too abstract the concept of RESTful ROA Api is more accurate and they work together. ROA means you represent and expose every resource and give access to the possible actions (verbs) to that resource. A resource must have at least one URI that represents it and could be the result of an algorithm (GET /search/?something)

Another principle of RESTful is stateless. You don’t have to coerce the server in any state before requesting something. That’s a principle broken very often. If I have to go from the step 1 to the step 2 in that order because something happens in the server in the step 1 that let me continue it’s probably you’re breaking the principle.

VERBS are PUT, POST, GET, DELETE and even when they exist they are not used very often HEAD, PATCH and OPTIONS.

There are several other concepts to cover a book, unfortunately a lot of pages are not even sufficient to explain RESTful APIs but I hope this summary is useful enough.

Published by maxriosflores

Solution Architect for a decade.
I designed, built and implemented software solutions for more than 25 years and every single day more interested on technology. I learned to code in a Texas Instruments with 16kb at 8 years old. I shared this passion with friends coding CZ Spectrums, MSX's and C64's. I worked in computers since my early 17's with super old tools like plain C and Quick Basic. I love math and computers as much as outdoors and family life.
View more posts