RESTFUL WEB SERVICES - Java EE Design Patterns - page 170

continued
I raised the issue and asked if that design was really following RESTful principles.
Of course, my words offended the project architect, and he started showing us the
REST API docs and how each client would work with OAuth and passing param-
eters via uniform resource locators (URLs). Nevertheless, the system was relying on
preserving the state rather than transferring it.
Just like fashionistas, developers and system designers love trends and want to look
trendy. However, without understanding the underlying principles and determining
whether they really address your concerns and problems, you may end up being the
weird‐looking guy who wanted to be trendy but failed to fully understand the tech-
nology. In their case, they had built a representative state preserving (RESP?) back
end instead of REST.
You will soon learn the elements that make up a URI.
Resource Naming
RESTful APIs are written for clients and should have meaning for the clients of those APIs. When
choosing nouns to name the resources, you should be familiar with the structure of the application's
data and how your clients are likely to use them. There are no dei ned rules as to how you should
name your resources, but there are conventions that, if followed, can help you create a set of self‐
descriptive resource names that others intuitively understand.
Nouns Not Verbs
You must name the resources after nouns, not verbs or actions. The purpose of the resource name
is to represent the resource. The HTTP method describes the action to be performed. The next
section covers the HTTP method in more detail. To represent a single user resource, you would
use the noun users to represent all users and the user's ID to identify the specii c user, like so:
users/123456 . An example of a non‐REST and badly formed URI would be users/123456/update ,
or it would include the action in a query string such as users/123456?action=update .
The nature of data is that it is hierarchical. So imagine that you want to represent all the posts
of the user with ID 123456 . You would use the noun posts to represent all posts and create the
URI users/123456/posts . Earlier, it was mentioned that the representation of the resource is
not the actual resource itself, but a representation of the resource, and the same resource can be
represented in different ways. To represent all posts by a specii ed user, you can use the URI posts/
users/123456 . Once you have a representation of a resource, you can decide what you want to do
with it by using one of the four HTTP methods. To retrieve a resource, you use the GET method, and
to create a resource, you use the POST method. More on this in the next section.
Self‐Descriptive
As you have seen, the nouns chosen should rel ect the resource they represent. Combining these
representations with identii ers makes the URI easy to interpret and intuitive to understand. If you
read a URI in combination with its HTTP method and it is not immediately obvious what resource
it represents, it has failed as a RESTful URI.