What is a RESTful Api?

First let's try to understand what is an Application Programming Interface (API)?

Analogy 1

Restaurant : Kitchen = Server, Customer (You) = Client and the Waiter = API

The waiter is structured to bring the meal based on the menu. That's an API. In short you need not go to the restaurants kitchen or speak to the chef. The waiter is the intermediary for you to get your meal. The menu defines what is available and what's not.

Analogy 2

Car : Engine = Server, Driver (You) = Client, Dashboard = API

We drive a car but we don't know how the engine works. The car company gave us a gear handle, accelerator, speedometer and steering wheel to control the car. That's an API, an interface to control the car.

I hope API in layman terms is clear. Now the Web is an information network on top of the Internet, accessible through your browser. It has a different architecture than other computer systems in many ways.

REST = Representational State Transfer

REST is an  architectural style to design systems like the Web.

An API is called RESTful API if it conforms to the following 4 rules.

1. Offer access through resources

clients and servers exchange commands: do this, do that. Suppose we want to model a to-do list in a non-REST way. In a technical language, that might look like this:

NOT REST

/changeTodoList.php?item=35&action=changeTitle&title=new_title

• Note how this is indeed an instruction: change something.

But a “changeTodoList” is not a thing, it's not a resource.

In the REST architectural style, servers only offer resources. Resources are conceptual things about which clients and servers communicate.

REST

/todolists/7/items/35/

This above thing is not a command, it is the address of a resource, a thing.

You can then use this address to manipulate the to-do list using standard operations, instead of interface-specific commands.

2. Represent resources by representations.

A resource is a thing—and we can describe those things in different formats. For instance, humans might want to see an HTML version, which your browser transforms into a readable layout. But sometimes, interfaces on the Web are used by machines, too. They need a different format, such as JSON.

In a non-REST way, different formats have different addresses:

NOT REST

• browser: /showTodoList.php?format=html
• application: /showTodoList.php?format=json

The problem is then that systems using different formats cannot communicate with each other, because they use different addresses for the same things!

In a REST system, addresses identify things, not formats, so all systems use the same address for the same thing. How can they get different formats then? They explicitly ask for it!

REST

• browser: “I want /todolists/7/, please give me HTML.”
• application: “I want /todolists/7/, please give me JSON.”

The technique that enables this is called content negotiation.

3. Exchange self-descriptive messages.

In a REST system, we should be able to interpret any message without having seen the previous one. Imagine the following conversation:

NOT REST

/search-results?q=todo

/search-results?page=2

/search-results?page=3

The first request gets search results for “todo”; the second request gets the second page of that. Now imagine that you only see the second request. How would you know as a server what to do?

In REST, each message stands on its own:

REST

/search-results?q=to-do

/search-results?q=todo&page=2

/search-results?q=todo&page=3

Note how each request can be interpreted by itself.

4. Connect resources through links.

How can you navigate a website you've never seen before? You use links!

You don't have to manually edit the address bar in your browser every time you go to a new page.

In machine interfaces, this is not always the case. Suppose an application asks for your to-do list. It might receive the following representation:

NOT REST

• /todolists/7/

{
  "name": "My to-dos",
  "items": [35, 36]
}

Now how can you get the items of the list?

Good question! We'd have to read the documentation for that.

In REST, resources connect to each other through hyperlinks:

REST

• /todolists/7/

{
  "name": "My to-dos",
  "items": ["/todolists/7/items/35/", "/todolists/7/items/36/"]
}

Note how you don't have to read the manual to know how you can retrieve the items of your list. You just follow the links.

Facts about REST

• Architecture style for designing networked applications
• Relies on stateless, client-server protocol, almost always HTTP
• REST was made was to treat server objects as resources. Eg: A blog post
• REST can be used any programming language
• A RESTful API means an API conforming the REST standards

HTTP Methods

GET: Retrieve data from a specified resource

POST: Submit data to be processed to a specified resource. Like the form element in HTML which has an action and a method section.

PUT: Update a specified resource

DELETE: Delete a specified resource

Others are HEAD, OPTIONS, PATCH but they are not very popular

Endpoints

The URI/URL where api/service can be accessed by a client application are called endpoints.

GET https://mysite.com/api/users

GET https://mysite.com/api/users/1

#OR

GET https://mysite.com/api/users/details/1

POST https://mysite.com/api/users

PUT https://mysite.com/api/users/1

# OR

PUT https://mysite.com/api/users/update/1

DELETE https://mysite.com/api/users/1 

# OR

DELETE https://mysite.com/api/users/delete/1

Authentication

Some API's require authentication to use their service. See some examples below

1. We send the token in the url itself

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

2. We send the token as a parameter

curl https://api.github.com/?access_token=OAUTH-TOKEN

3. We sent the token as an client id with a secret key

curl 'https://api.github.com/users/whatever?client_id=xxxx&client_secret=yyyy'

Conclusion

REST API development is probably one of the most pleasant processes in modern web and mobile services development. There are no browser, operating system, and screen-size zoos, and everything is fully under your control, at your fingertips.