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.
Identify the resources in the application that you want to expose as a RESTful service.
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 http://www.ibm.com/ or http://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 http://www.example.com/bookstore/books as the collection resource URL, http://www.example.com/bookstore/books/ISBN123 as a unique book resource URL, and you can use http://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 http://www.example.com/bookstore/books/ retrieves a list of book URLs that can include http://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 http://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: http://www.example.com:9060/example/store/bookstore/books.
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.
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.