glennblock/gist:5608543

## gistfile1.txt
_REST_, or Representational State Transfer is probably one of the most misunderstood terms in Web API development today. Where REST is misunderstood is that most people use REST as synonymous with anything that is easy to access over HTTP and forget about the constraints completely.

The term's roots are from Roy Fielding's previously mentioned dissertation on network based architecture (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). In it, Roy describes REST as an architectural style for distributed hypermedia systems. What he is saying is that REST is not a technology, it is not a framework, and it is not a design pattern. It is a style. There is no "One True Way" to do REST and as a result, many flavours of RESTful systems. What they have in common however, and  most importantly, is that RESTful systems manifest iteself in a set of constraints, which will be mentioned in more depth in this section.

The other part of the misunderstanding is that you MUST build a RESTful system. This is also not the case. The RESTful constraints are designed to create a system that achieves a certain set of goals in particular a system that can evolve over a long period of time and which can tolerate many different clients, and many different changes without breaking those clients.

===== REST Constraints =====
REST defines the following 5 constraints as part of the style.

* Client-Server. A RESTful system is designed to separate out the UI concerns from the backend. Clients are decoupled from the server thus allowing both to evolve independently.

* Stateless. Each request in a RESTful system all of the application state is kept on the client and transferred in the request. This allows the server to receive all the information it needs to process the request without having to track each individual client. Removing statefullness from the server allows the application to easily scale.

* Cache. Data within a request must be able to be identified as cachable. This allows client and server caches to act on behalf of the origin server and to return cached representations. Cachability allows latency to be greatly reduced, user-perceived performance to increase, and improves overall scale of the system as it reduces the load on the server.

* Uniform interface. RESTful systems use a standardized interface for system interaction.

** Identification of resources. This means that the point of interaction in a RESTful system is a _resource_. This is the same resource that we discussed earlier.

** Self-descriptive messages. This means that each message contains all the information necessary for clients and servers to interact. This includes the URI, HTTP method, headers, media type and more.

** Manipulation of resources through representations. As we covered previously, a resource can have one or more representations. In a RESTful system it is via these representations that resource state is communicated.

** Hypermedia as the engine of application state (HATEOAS). Previously we discussed hypermedia and the role it plays in driving the flow of the application. That model is a core component of a RESTful system.

Building a RESTful system is not free, and not necessarily easy, however it can be worth the investement depending on the system's needs. For this reason this book does not focus on REST but rather focuses on evolvability and techniques to achieve that when building your Web APIs. Each of these techniques is a pathway toward a fully RESTful system but they provide benefit in their own right.

In other words, focus on the needs of your system and not whether you can stamp it with a "REST" badge or not.

For more clarification on REST, Kelly Sommers (@kellabyte) has a well written post which covers this topic in more detail (http://kellabyte.com/2011/09/04/clarifying-rest/)
	_REST_, or Representational State Transfer is probably one of the most misunderstood terms in Web API development today. Where REST is misunderstood is that most people use REST as synonymous with anything that is easy to access over HTTP and forget about the constraints completely.

	The term's roots are from Roy Fielding's previously mentioned dissertation on network based architecture (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). In it, Roy describes REST as an architectural style for distributed hypermedia systems. What he is saying is that REST is not a technology, it is not a framework, and it is not a design pattern. It is a style. There is no "One True Way" to do REST and as a result, many flavours of RESTful systems. What they have in common however, and most importantly, is that RESTful systems manifest iteself in a set of constraints, which will be mentioned in more depth in this section.

	The other part of the misunderstanding is that you MUST build a RESTful system. This is also not the case. The RESTful constraints are designed to create a system that achieves a certain set of goals in particular a system that can evolve over a long period of time and which can tolerate many different clients, and many different changes without breaking those clients.

	===== REST Constraints =====
	REST defines the following 5 constraints as part of the style.

	* Client-Server. A RESTful system is designed to separate out the UI concerns from the backend. Clients are decoupled from the server thus allowing both to evolve independently.

	* Stateless. Each request in a RESTful system all of the application state is kept on the client and transferred in the request. This allows the server to receive all the information it needs to process the request without having to track each individual client. Removing statefullness from the server allows the application to easily scale.

	* Cache. Data within a request must be able to be identified as cachable. This allows client and server caches to act on behalf of the origin server and to return cached representations. Cachability allows latency to be greatly reduced, user-perceived performance to increase, and improves overall scale of the system as it reduces the load on the server.

	* Uniform interface. RESTful systems use a standardized interface for system interaction.

	** Identification of resources. This means that the point of interaction in a RESTful system is a _resource_. This is the same resource that we discussed earlier.

	** Self-descriptive messages. This means that each message contains all the information necessary for clients and servers to interact. This includes the URI, HTTP method, headers, media type and more.

	** Manipulation of resources through representations. As we covered previously, a resource can have one or more representations. In a RESTful system it is via these representations that resource state is communicated.

	** Hypermedia as the engine of application state (HATEOAS). Previously we discussed hypermedia and the role it plays in driving the flow of the application. That model is a core component of a RESTful system.

	Building a RESTful system is not free, and not necessarily easy, however it can be worth the investement depending on the system's needs. For this reason this book does not focus on REST but rather focuses on evolvability and techniques to achieve that when building your Web APIs. Each of these techniques is a pathway toward a fully RESTful system but they provide benefit in their own right.

	In other words, focus on the needs of your system and not whether you can stamp it with a "REST" badge or not.

	For more clarification on REST, Kelly Sommers (@kellabyte) has a well written post which covers this topic in more detail (http://kellabyte.com/2011/09/04/clarifying-rest/)