29 Tips: Build Appealing REST Resources for Fun and Profit
A clear design philosophy can make REST implementation Fun and Profitable. Unfortunately, a company attempting to implement REST without guidelines will waste vast sums of money.
Thinking about implementing REST services? The following tips will help you plan a successful REST implementation:
- Consider REST if data returned is not dynamically generated and can be cached
- Use REST when bandwidth is particularly important and limited
- Use REST for lightweight resource elements within an organization only for integration purposes.
- Consider REST for web delivery or aggregation into existing websites because services can be exposed with XML and JSON. HTML pages can consume these resources without significantly refactoring an existing website architecture.
- Consider REST when exposing components across a firewall and to control clients who access the resource.
- Consider REST when supporting AJAX based clients.
- A REST resource should be completely stateless.
- A concrete implementation of a REST resource MUST follow four basic design principles:
- Use HTTP methods explicitly
- Be stateless
- Expose directory structure-like URIs
- When creating a resource in a REST network (i.e., the Web) conceptualize and identify entities that need to be exposed as resources. Look at the entire system and see what nouns (data) can be identified.
- Create a URI to each resource and ensure the resource is a noun, not a verb.
- Categorize resources in REST according to if a client can receive a representation of the resource, or if a client can modify (add to) the resource.
- Response formats should be specified using a schema.
- REST URIs should be nouns and easy to recognize.
- Hide server-side scripting technology file extensions (.jsp, .php, .asp), to allow porting to something else without changing the URIs.
- Keep everything lowercase.
- Substitute spaces with hyphens or underscores (one or the other).
- Avoid query strings as much as possible.
- Use a “/” in the URI to express parent-child relationships.
- REST URIs should be static in nature so that when the resource changes or the implementation of the service changes, the link stays the same to allow bookmarking.
- Users of REST resources should not derive metadata from the URI.
- Response payloads in REST should be simple, human readable and connected.
- Give client applications the ability to request a specific content type best suited for the client application.
- All resources transferred over REST must be marked cacheable, or non-cacheable (at minimum).
- REST deployments should be layered.
- Use a resource based approach for mobile devices.
- Use HTTP error codes along with suitable additional information in a header like X-Application-Error-Code: for differentiating multiple mappings to the same code used for REST exception.
- Do not return empty XML documents in case of error.
- Always return a response document.
- All REST responses should return a request ID like for troubleshooting purposes.