Defining the URI patterns for resources in RESTful applications
Representational State Transfer (REST) services are based on manipulating resources. Resources for RESTful services are addressable, and URLs are the primary way of achieving addressability in REST.
Before you begin
Identify the resources in the application that you want to expose as a RESTful service.
About this task
URLs are used to specify the location of a resource. Interaction between the server and client is based on issuing HTTP operations to URLs. Defining URL patterns is important because URLs often have a long lifetime so that clients can directly address a resource long after the resource is initially discovered.
URLs
are typically used when you enter addresses to web browsers, such
as https://www.ibm.com/
or https://www.example.com/bookstore/books/ISBN123
.
Although URLs are not required to be understandable by users, RESTful
services that provide logical URLs in understandable patterns enable
client application developers to work efficiently.
RESTful
clients use URLs to manipulate resources. Each resource must have
its own unique URL. Some URL patterns have a collection path with
a unique identifier appended. For example, you can use https://www.example.com/bookstore/books
as
the collection resource URL, https://www.example.com/bookstore/books/ISBN123
as
a unique book resource URL, and you can use https://www.example.com/bookstore/books/ISBN123/authors
to
retrieve a collection resource describing ISBN123
authors.
The application developer must carefully consider the granularity of URLs because it can affect usage of the application and performance. For example, you can include the author information of a book as part of the book resource or you can define the author information as a unique resource with its own URL that is referenced in the book resource. Depending on the reuse of resources, it might be more efficient to define a separate resource for the author information that is referenced in a hyperlink of the book resource for cases when the author writes a different book.
After an initial URL is given to a client,
subsequent related requests are discoverable by parsing the current
resource. In the book example, a GET request to https://www.example.com/bookstore/books/
retrieves
a list of book URLs that can include https://www.example.com/bookstore/books/ISBN123
.
Because
systems rely on resources being available, URLs typically have longevity.
Because HTTP has built-in status codes for redirection, such as the
301 moved permanently code and the 307 temporarily redirected code,
users and clients with caches often reuse previously discovered URLs
first. You can additionally consider including a version identifier
in the URL pattern, such as https://www.example.com/bookstore/v2/books/ISBN123
.
Like the planning involved to define an interface using Java™ code, be sure to carefully choose your
URL patterns because of expected longevity.
In Java API for RESTful Web Services (JAX-RS), you must add @Path annotations to the Java class files or the Java methods to define the relative URL of the resource. You can use JAX-RS subresource locators and subresource methods to define resources. Use parameters, such as the path parameter or matrix parameter, in the URL to identify the resource.
The value in the @Path annotation defines the
relative part of the full URL to your resource. The base URL is derived
from the domain, port, application module context root, and any URL
pattern mappings in the web.xml file of the application module. For
example, if the domain is www.example.com
, the port
is 9060
, the module context root is example
,
the servlet URL pattern is store/*
, and the value
of the @Path annotation is /bookstore/books
. The
full URL is: https://www.example.com:9060/example/store/bookstore/books.
Procedure
Results
You have created a URL to identify your resources for your RESTful service. By considering issues with URL patterns early in the application design, the RESTful service increases its usability and value over an extended time.
What to do next
The resource at the defined URL exists. However, the resource does not yet have any methods to handle HTTP method actions such as GET, POST, PUT, or DELETE. See the defining resource methods for RESTful applications to learn more about defining capabilities of resources using supported HTTP methods.