Java Web Services: Up and Running, 2nd Edition

HTTP as an API

HTTP can be viewed as an API. Among frameworks for developing websites and RESTful web services, Rails has pioneered this view of HTTP, which deliberately blurs the distinction between websites that deliver HTML and web services that deliver XML or JSON. In a well-designed Rails application, a GET request for the URI /products is equivalent to the same request for /products.html, and an HTML list of products is returned in response. A GET request against /products.json or /products.xml would return the same list but in JSON or XML, respectively. Rails has an often-copied idiom for combining URIs and HTTP verbs into a RESTful route—the route that a request takes to the code that handles the request. The Rails routing style is an elegant yet practical use of HTTP as an API. Table 1-3 is a summary of the Rails approach. In a URI, a term such as :id, which begins with a colon character, indicates a placeholder or parameter, in this case a placeholder whose intended value is a numerical identifier such as 27.

Table 1-3. Rails routing idioms

HTTP verb	URI (Name)	Meaning
GET	/products	Read all products
POST	/products	Create a new product from information in the POST body
GET	/products/new	Read the form to create a new product
GET	/products/:id/edit	Read the form to edit an existing product
GET	/products/:id	Read a single product
PUT	/products/:id	Update a product with information in the POST body
DELETE	/products:id	Delete the specified product

These verb/name pairs are terse, precise, intuitive, ...