Friday, March 19, 2010

REST-* Architectural Goals

Looking through the REST-* collateral I’m struck by how much it relies on common sense over technical pedantry. The high-level architectural goals can be found here, and I’ve pasted the content in below just to make it easy. I particularly like the “Edge cases should be extensions” goal.

Architectural Goals

Low barrier to entry
Clients that use the specification should have a very low barrier to entry. They shouldn't need to install a library or large stack of software to use a specification. An HTTP client or web server provided by the language or platform should be enough to implement or use implementations of the specification.

Edge Cases should be Extensions
Edge cases that complicate the main specification should be defined in a separate sub-specification. Extensions should strive to be layered on top of the main specification by using facilities like HATEOAS and HTTP conneg to provided their features.

Pragmatic REST
While a specification should strive to follow RESTful principles, simplicity should never take a back seat to being a pure RESTafarian. If you need to bend the rules of REST to create a simpler design, then that's the path that should be taken.

80/20 Rule
Specifications should remain simple. Many times in specification efforts, edge cases cause a lot of bloat and complexity within the specificaiton making it difficult to use, understand, and implement. Specifications should cover 80% of the most common use cases. Edge cases should not be in the main specifications. REST should be able to provide the facilities (HATEOAS, HTTP conneg) to abstract away edge cases.

Avoid Envelope formats
Whenever possible, avoid envelope formats. Examples of envelope formats are SOAP and Atom. Envelope formats encourage tunneling over HTTP instead of leveraging HTTP. They also require additional complexities on both the client and the server. In most cases HTTP headers should be enough to transfer metadata about the request, response, or resource.

Isolate data formats to extensions
If possible, specifications should try not to define new data formats.

1 comment:

hong_hai_long said...

I just wanted to comment your blog and say that I really enjoyed reading your blog post here. It was very informative and I also digg the way you write! Keep it up and I'll be back to read more soon mate
windows activation