Designing RESTful Services - RESTful Java with JAX-RS 2.0 - page 19

example, an HTTP GET on a particular resource should be read-only. It should not change
the state of the resource it is invoking on. Intermediate services like a proxy-cache, a CDN
(Akamai), or your browser rely on you to follow the semantics of HTTP strictly so that they
can perform built-in tasks like caching effectively. If you do not follow the definition of each
HTTP method strictly, clients and administration tools cannot make assumptions about your
services, and your system becomes more complex.
Let's walk through each method of our object model to determine which URIs and HTTP
methods are used to represent them.
Browsing All Orders, Customers, or Products
The Order , Customer , and Product objects in our object model are all very similar in how
they are accessed and manipulated. One thing our remote clients will want to do is to browse
all the Orders , Customers , or Products in the system. These URIs represent these objects
as a group:
/orders
/products
/customers
To get a list of Orders , Products , or Customers , the remote client will call an HTTP GET
on the URI of the object group it is interested in. An example request would look like the fol-
lowing:
GET / products HTTP / 1.1
Our service will respond with a data format that represents all Orders , Products , or Cus-
tomers within our system. Here's what a response would look like:
HTTP / 1.1 200 OK
Content - Type: application / xml
< products >
< product id = "111" >
< link rel = "self" href = "http://example.com/products/111" />
< name > iPhone </ name >
< cost > $199 . 99 </ cost >
</ product >
< product id = "222" >
< link rel = "self" href = "http://example.com/products/222" />
< name > Macbook </ name >
< cost > $1599 . 99 </ cost >
</ product >