29 Tips: Build Appealing REST Resources for Fun and Profit

29 Tips: Building Appealing Services for Fun and ProfitA 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 29 tips will help you plan a successful REST implementation:

  1. Consider REST if data returned is not dynamically generated and can be cached. The caching infrastructure of web servers and other intermediaries can inherently be leveraged to improve performance. However, a developer MUST take care because such caches are limited to the HTTP GET method for most servers.
  2. Use REST when bandwidth is particularly important and limited. REST is RECOMMENDED for limited-profile devices such as PDAs and mobile phones. The overhead of headers and additional layers of SOAP elements on the XML payload must be restricted.
  3. Use REST for lightweight resource elements within an organization only for integration purposes.
  4. 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.
  5. Consider REST when exposing components across a firewall and to control clients who access the resource.
  6. Consider REST when supporting AJAX based clients.
  7. A REST resource is completely stateless. A good test to consider is if an interaction can survive a restart of the server.
  8. A concrete implementation of a RESTresource MUST follow four basic design principles:
    • Use HTTP methods explicitly
    • Be stateless
    • Expose directory structure-like URIs
    • Transfer XML, JavaScript Object Notation (JSON), or both.
  9. 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.
  10. Create a URI to each resource and ensure the resource is a noun, not a verb.
  11. 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.
  12. Response formats should be specified using a schema. For those REST resources that require a POST or PUT, provide a schema to specify the format of the response. When using micro formats like JSON, the specification should be shared with consumers.
  13. REST URIs should be nouns and easy to recognize. One way to achieve such a level of usability is to define a directory structure. The URI is hierarchical, rooted at a single path, and branching from it are sub-paths exposing additional resource areas. A URI is not merely a slash-delimited string but rather a tree with subordinate, and super ordinate branches connected at nodes.
  14. Hide the server-side scripting technology file extensions (.jsp, .php, .asp), to allow porting to something else without changing the URIs.
  15. Keep everything lowercase.
  16. Substitute spaces with hyphens or underscores (one or the other).
  17. Avoid query strings as much as possible.
  18. Use a “/” in the URI to express parent-child relationships.
  19. REST URIs should be static so that when the resource changes or the implementation of the service changes, the link stays the same to allow bookmarking.
  20. Users of REST resources should not derive metadata from the URI. Consider deriving such information from query strings.
  21. Response payloads in REST should be simple, human readable and connected.
  22. Give client applications the ability to request a specific content type best suited for the client application. This will allow constructing a service that makes use of the built-in HTTP Accept header, where the value of the header is a MIME type (e.g. application/json, application/xml, application/xhtml+xml)
  23. All resources transferred over REST must be marked cacheable, or non-cacheable (at minimum).
  24. REST deployments should be layered. The client in each layer making a request to a server in the next layer may proxy it to a server in another layer.  REST services should be agnostic to such layering. Layering allows for scalability, security, and other features. Typically, REST requests traverse the front-end connectors (IP filtering, URL mapping, time-based filtering, cookie-based filtering, duplication-detection filter ), and backend filters (application based processing).
  25. Use a resource based approach for mobile devices.
  26. 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. HTTP codes used should be in accordance with standards (2xx as success, 3xx as redirection, 4xx as client error, and 5xx as server error.
  27. Developers should not return empty XML documents in case of error.
  28. Always return a response document.
  29. All REST responses should return a request ID like for troubleshooting purposes.

Leave a Reply