How should I build a RESTful API? /Act I. - What is REST?/

To understand what is a RESTful API, first we have to clear what is REST. (this post is far away from a full review of REST, just a quick one to help building a RESTful API, you can find deeper reviews among the references [at the bottom])

REST = REpresentational State Transfer
The elaboration of REST is a part of Roy Fielding's Dissertation

So, what is REST?

Architectural style for distributed hypermedia systems such as World Wide Web

So, REST is an architectural style. Not identical to HTTP, not an API and it's not just one and only for APIs. It is a set of constraints to build a simplified and decoupled system such as Web.

But we want to create an API in REST style, so we'll use the REST constraints to achieve our goal!

Before move on the architectural constraints, first we should take a quick look at the architectural elements.

Architectural elements: (just a minimal representation)

• Data elements

"The key aspect of REST is the state of the data elements, its components communicate by transferring representations of the current or desired state of data elements"

• Resources 
• "Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on"
• Representations 
• "It is something that is sent back and forth between clients and servers"
• "Never send or receive resources, only their representations"
• "Sequence of bytes, HTML document, archive document, image document"
• Part (it can be the entire) of the resource state

 Architectural constraints:

• Uniform interface

Defines the Interface between Client and Server. Simplifies and Decouples the Architecture. Uniform interface has 4 constraints:

• Identification of Resources
• "Resources must have a unique identifier which can be use to retrieve a resource (e.g. URI)"
• Manipulation of Resources through Representations
• "Resources can be updated (or added) by sending representations from the client to the server"
• Self-descriptive messages
• "It means each message contains all the information necessary to complete the task"
• Hypermedia As The Engine Of Application State
• HATEOAS
• "The ability to navigate resources through hyperlinks/hypermedia is the hallmark of REST" 
• Layered system 
• A client cannot rely a direct connection to the end server
• There can be intermediary layers between the client and the end server
• An intermediary can be a load-balancer or proxy...
• Client-Server
• Separation of concerns
• Improves client portability
• Server can be simpler, more scalable
• Stateless
• "each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server"
• Cacheable
• "the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable"
• Code on demand (optional)
• "server can extend the client functionaility by sending back scripts or code"
• The code is the know-how to process the representation of the given resource

Next time we'll move on the discussion of a RESTful API!
 
References:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm 
http://blog.restlet.com/tag/rest-api/
http://www.slideshare.net/kjbuckley/doing-rest-right-3385800
http://www.sitepen.com/blog/2010/05/09/resource-oriented-programming/
http://mrbool.com/rest-architectural-elements-and-constraints/29339
http://nirmata.com/2013/10/rest-apis-part-1/
http://exyus.com/articles/rest-the-short-version/