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

...
</ products >
One problem with this bulk operation is that we may have thousands of Orders , Customers ,
or Products in our system and we may overload our client and hurt our response times. To
mitigate this problem, we will allow the client to specify query parameters on the URI to
limit the size of the dataset returned:
GET / orders ? startIndex = 0 & size = 5 HTTP / 1.1
GET / products ? startIndex = 0 & size = 5 HTTP / 1.1
GET / customers ? startIndex = 0 & size = 5 HTTP / 1.1
Here we have defined two query parameters: startIndex and size . The startIndex para-
meter represents where in our large list of Orders , Products , or Customers we want to start
sending objects from. It is a numeric index into the object group being queried. The size
parameter specifies how many of those objects in the list we want to return. These paramet-
ers will be optional. The client does not have to specify them in its URI when crafting its re-
quest to the server.
Obtaining Individual Orders, Customers, or Products
I mentioned in the previous section that we would use a URI pattern to obtain individual
Orders , Customers , or Products :
/ orders /{ id }
/ products /{ id }
/ customers /{ id }
We will use the HTTP GET method to retrieve individual objects in our system. Each GET
invocation will return a data format that represents the object being obtained:
GET / orders / 233 HTTP / 1.1
For this request, the client is interested in getting a representation of the Order with an or-
der id of 233 . GET requests for Products and Customers would work the same. The
HTTP response message would look something like this:
HTTP / 1.1 200 OK
Content - Type: application / xml
< order id = "233" >...</ order >
The response code is 200, “OK,” indicating that the request was successful. The Content-
Type header specifies the format of our message body as XML, and finally we have the actu-
al representation of the Order .