...

RESTful refers to representational state transfer which is used to abstract the state and the interaction of a resource over the HTTP protocol. A RESTful server will provide a representation of the state of the communication along with the transfer. Two differents different clients requesting the same idempotent command on two servers but the same resource and on two servers will generate the same result on a RESTful API.

This document will only, briefly, cover the general mindset over a RESTful development and, since RESTful systems are not normalized yet, it will only cover a vision of a good RESTful development. Still, the concept is quite strict. It is normal and intentional that the reference documents provided doesn't have the exact same vision of a RESTful API because following the guidelines by the book may cost a lot in processing and make the communication heavy in information. The most important part is to build yourself a toolkit full of tools you do understand completely. Once you have your toolkit you will be able to make the right decision for your API.This document will not explain what is the HTTP protocol.

RESTful API

The general idea behind the representational state transfer (REST) is to use the full capabilities of the HTTP protocol in order to produce a common way to interact with any resources. Also, the state of the communication is neither kept on client or server side but within the communication between the two. Both must provide all the necessary information to fully complete the needs of both the client and the server. The server will return a status code meaningful and the client must understand it and make a request according to the information the server just provided. The only elements the client can be certain is the fact that the URI is permanent and the server will provide a status code on the request. The server however can't be certain of anything regarding the client but the fact that it will use the appropriate METHOD for the request. Therefore, the server must provide a meaningful status code and coherent information. It is also necessary that the server provide URIs for further navigation by the client.

It is important to stay coherent with your API(s).

HTTP as common interface

HTTP is a client/server based protocol defining methods to interact with the state of the resources of the server. These methods are GET, POST, PUT, DELETE, OPTIONS and HEAD. Altogether these operation covers the majority of the resources use cases: read, add, update and delete. OPTIONS and HEAD might seem left behind however they are used as the minimal documentation for your APIs. With such options on all given resources, many common pattern can be avoided such: "GET /createFoo", "GET /updateFoo", "POST /deleteFoo", etc. Those can be replaced by "POST /foo", "PUT /foo", "DELETE /foo". In other words, the actions verbs are directly supported by the protocol leaving each field a single task:

...

The most predictable way to built a REST server is to use all the tools how they were designed to be used. Therefore creating new header for the simple purpose of your API implementation is not something one would call predictable. Having an APi API predictable will allow other devices to understand and use your services even if they are not specifically designed for that purpose.

...

Resource is a vague concept and should be interpreted as the context needs it. Il It is possible to have a resource representing a collection of element such : /order. This collection of resources is referenced by a single URI. Each element of the the collection can still be accessible through: /order/12345 or /order?id=12345. The general idea is to allow the client to execute an action over a group of resources. If this feature is not important, you don't need a collection.

...

As an example of composition take a Cafe. The cafe can have multiple information such customers, orders, supplies and so on. However, it is nice to be able to access the cafe resource for all the informations information it has to give.

That Cafe, Foo's Cafe, could be identified as /fooscafe and would provide information like addresses or menu. These resources could be accessed individually but makes much more sense if the are accessed through the aggregation: /fooscafe/menu, /fooscafe/store.

...

The limits of the RESTful API is when actions must be merged. An example for this is the merging. Imagine that your have a REST server providing file versioning capabilities. It is a known issue that at some point your will have to merge files. How could this complex action be done in with HTTP methods? Many would at first extend the POST method, add an additional header or add a new method to the protocol. All these choices break predictability of the API. First of all, we have to analyse analyze our needs. Will the files be merged on client or server side. If it is merged on client side the answer is simple: GET /file1, GET /file2 and POST /mergedfile. However, merging on the server side is not as simple but not least feasible. The first step would be to send the server a POST about your intention over the files to merge. The body could look like the following JSON:

...

Then the server could respond with the metadata of the merged file.It is more appropriate in this kind of server to build a permissive one than to

Security

REST doesn't specify any security system. In fact, HTTP have many ways to protect the information such different authentications and HTTP secure.

It is recommended to at least have one layer of security. It could reduce the exposure to security failures greatly. 

...

One of the strengths of a RESTful design built on top of the HTTP protocol is that is inherently highly extensible. New functionalities functionality can be added without affecting any existing resource..

JavaScript, JQuery and REST utility

...