Java Reference
In-Depth Information
The
start
query parameter identifies the starting index for our customer list. The
size
para-
meter specifies how many customers we want returned from the query.
This is all well and good, but what we've just done is increased the amount of predefined
knowledge the client must have to interact with the service beyond a simple URI of
/cus-
tomers
. Let's say in the future, the server wanted to change how view sets are queried. For
instance, maybe the customer database changes rather quickly and a start index isn't enough
information anymore to calculate the view. If the service changes the interface, we've broken
older clients.
Instead of publishing this RESTful interface for viewing our database, what if, instead, we
embedded this information within the returned document?
<customers>
<customers>
<link rel=
"next"
href="http://example.com/customers?start=2
&
size=2"
type="application/xml"/>
<customer
<customer id=
"123"
>
<name>
<name>
Bill Burke
</name>
</name>
</customer>
</customer>
<customer
<customer id=
"332"
>
<name>
<name>
Roy Fielding
</name>
</name>
</customer>
</customers>
</customer>
</customers>
By embedding an Atom link within a document, we've given a logical name to a state trans-
ition. The state transition here is the next set of customers within the database. We are still
requiring the client to have predefined knowledge about how to interact with the service, but
the knowledge is much simpler. Instead of having to remember which URI query parameters
to set, all that's needed is to follow a specific named link. The client doesn't have to do any
bookkeeping of the interaction. It doesn't have to remember which section of the database it
is currently viewing.
Also, this returned XML is self-contained. What if we were to hand off this document to a
third party? We would have to tell the third party that it is only a partial view of the database
and specify the start index. Since we now have a link, this information is all a part of the doc-
ument.
By embedding an Atom link, we've decoupled a specific interaction between the client and
server. We've made our web service a little more transparent and change-resistant because
we've simplified the predefined knowledge the client must have to interact with the service.
Finally, the server has the power to guide the client through interactions by providing links.
