When defining URLs, the idea is not to define everything but to define the operations that the web application exposes. The URL is defined in the same way that a JavaScript function is defined, in that specifics are bound when used. The following URLs would be used to realize this application:
• http://mydomain.com/books/[ISBN]: Associates the URL with a book that has the indicated ISBN number.
• http://mydomain.com/books/[ISBN]/comments: Associates the URL with the comments of a book identified by the ISBN number.
• http://mydomain.com/books/[ISBN]/comments/[username]: Associates the URL with a user’s comments about a book identified by the ISBN number. The user is identified by username. • http://mydomain.com/users/[username]: Associates the URL with a user identified
by username.
• http://mydomain.com/users/[username]/books: Associates the URL with the books owned by the user identified by username.
• http://mydomain.com/users/[username]/comments: Associates the URL with the comments made by the user identified by username.
• http://mydomain.com/users/[username]/wishlist: Associates the URL with the wish list of books wanted by the user identified by username.
• http://mydomain.com/search/books: Associates the URL with a search for a specific book. • http://mydomain.com/search/users: Associates the URL with a search for a specific user.
Looking at the different URLs, you can see that what is being illustrated is the logical orga- nization of data associated with a URL. The first URL returns a representation of the book that may include comments about the book. Yet the comments associated with a book have their own URLs. A bit of thought about the implementation of the book URL would have the returned content include the comments of the book. What happens is not the inclusion of the comments in the book, but the inclusion of links to the comments of the book. When multiple items are being requested, do not create a URL that represents a list of resources. As in the example, asso- ciate the list of resources with a root-like URL (for example, /[ISBN]/comments). The included comments links would be associated with a description.
To understand this way of linking, consider the following example book definition retrieved from the URL http://mydomain.com/books/12345 that has been abbreviated to illustrate the referencing of comments:
<Book ISBN="12345" xmlns:xlink="http://www.w3.org/1999/xlink"> <Title>My Book</Title>
<Author>Joe Smith</Author> <Comment
xlink:href="/comments/maryjane" xlink:label="My Comment On Joe Smith" xlink:title="This book is not great">
<!-- Optional but here a short description could be added --> </Comment>
</Book>
The book is defined by using the Book XML tag and the child tags Title and Author. The important tag in this example is the Comment XML tag, which uses XML XLink attributes (href,
label, title) to define references to the full comments. Defined as a child element within the
Comment XML tag is an XML comment that says extra descriptive information could be added. The reason for the extra descriptive information is to allow a richer temporary descriptor of the
Comment. However, under no circumstances should the description information be manipulated by the client and assigned to the book URL. If a comment is to be updated or manipulated, the comment URL referenced by the Comment tag is used.
Consider the URLs http://mydomain.com/books/[ISBN]/comments and http://mydomain. com/users/[username]/comments. Both URLs reference a set of comments, but the comments displayed are different. These URLs provide an example of filtering URLs that illustrate different perspectives of the same underlying data. The problem with these URLs is, who owns the comment? Is the comment owned by the book or by the user? The answer is that it does not matter, because the underlying data will be referenced by using an individual URL. An example of this is the following URLs: http://mydomain.com/books/[ISBN]/comments/12345 and http:// mydomain.com/users/[username]/comments/12345. Notice how the individual comment is refer- enced by using a unique comment identifier. This is important because the comment 12345
should be identical when found by navigating to a book or navigating to a user.
Now consider the URLs http://mydomain.com/search/books and http://mydomain.com/ search/users. These are action URLs that are used to generate a result set that depends on the HTTP query string. This means doing an HTTP PUT and DELETE will have no effect, and an error should be generated. If the URL http://mydomain.com/search/users is requested, all users are returned. If, however, the URL http://mydomain.com/search/users?username=J* is requested, all users that have a username starting with J are returned. The format of the query string should always be flexible and should not require all parameters to be specified. For example, if you can search for users by using a username and age, you don’t have to always specify a username and age. Maybe sometimes only the username is specified, other times an age, and sometimes both a username and age. It is even possible in the URL to add a request for a specific formatting of the data (for example, format=xml). This is useful when the returned data should be in one format even though the client requesting the data usually gets another format.
When defining a resource URL, it is important to consider what the URL is being used for. Is it being used to represent a user (for example, http://mydomain.com/user)? Is it used to represent information (for example, http://mydomain.com/news/column/jack)? Is the information created
in a time-dependent fashion (for example, http://mydomain.com/news/column/jack/current
for current news and http://mydomain.com/news/column/jack/2005-10-10 for an archived news item)? You must remember that the URL represents a resource that the HTTP server is responsible for converting into a representation. The client is not responsible for knowing what technologies or files are stored on the server side, because that is a complete dependency of the HTTP server.