Who Should Read This Document
This best-practices document is intended for developers who are interested in creating RESTful Web services that provide high reliability and consistency across multiple service suites. By following these guidelines, services are well positioned for rapid, widespread, public adoption by both internal and external clients.
The guidelines in this document are also appropriate for support engineers where they desire to services developed using these best practices. While their concerns may be focused on caching practices, proxy rules, monitoring, security and such, this document may be useful as an overarching service documentation guide of sorts.
Additionally, management personnel may benefit from these guidelines by endeavoring to understand the effort required to create services that are publicly consumable and offer high levels of consistency across their service suites.
There are numerous resources on best practices for creating RESTful web services (see the Resources section at the end of this document). Many of the available resources are conflicting, depending on when they were written. Plus, reading and comprehending several books on the subject in order to implement services “tomorrow” is not doable. In order to facilitate the quick uptake and understanding of RESTful concepts, without requiring the reading of at least three to five books on the subject, this guide is meant to speed up the process—condensing REST best practices and conventions into just the high points with not a lot of discussion.
REST is more a collection of principles than it is a set of standards. Other than its over-arching six constraints nothing is dictated. There are “best practices” and de-facto standards but those are constantly evolving—with religious battles waging continuously.
Designed to be brief, this document provides recommendations and some cookbook-style discussion on many of the common questions around REST and provides some short background information to offer support for effective creation of real-world, production-ready, consistent RESTful services. This document aggregates information available in other sources, adapting it with experience gained through hard knocks.
There is still considerable debate as to whether REST is better than SOAP (and vice versa), and perhaps there are still reasons to create SOAP services. While touching on SOAP, this document won’t spend a lot of time discussing the relative merits. Instead, because technology and the industry marches on, we will proceed with the assumption that leveraging REST is the current best practice for Web service creation.
The first section offers an overview of what REST is, its constraints, and what makes it unique. The second section supplies some quick tips as little reminders of REST service concepts. Later sections go more in depth to provide the Web service creator more support and discussion around the nitty-gritty details of creating high-quality REST services capable of being publicly exposed in a production environment.