Table of Contents
Understanding how to interact with resources and how to interpret their representations is central to the RESTful approach. This chapter describes in detail the resources that are available; in effect, the API for using domain objects exposed using Restful Objects.
In order to invoke a HTTP method on a resource, the URL must be constructed correctly. After that, the client code then needs to handle the response.
Each of the resources is defined as interfaces annotated using
javax.ws.rs (JAX-RS)
annotations. JAX-RS is the Java API
for Restful Web Services, part of Java EE 6. Its annotations are used by
JAX-RS libraries such as RestEasy, or Jersey (the latter is the
reference implementation). These libraries expose the resources as
endpoints and route requests through to server-side methods (implemented
by Restful Objects).
As such, we can use these interfaces as a way of describing the resources provided by Restful Objects. Let's go through each in turn.
To start with, we have
HomePageResource:
import javax.ws.rs.GET;
import javax.ws.rs.Produces;
public interface HomePageResource {
@GET
@Produces( {"application/xhtml+xml", "text/html"} )
public String resources();
}Because there is no @javax.ws.rs.Path
annotation, this in effect says that the root URL "/" (eg http://localhost:8080/) is a valid
resource. What you'll get back is an XHTML page that
identifies the current user (in exploration mode this is always
hard-coded), and then lists the resources available: the services (ie
repositories), the specifications (metamodel), and details on the
current user.
These blocks are always present on every page.
Meanwhile the raw XHTML - what your client code must parse - looks something like:
<?xml version="1.0"?>
<html>
<head><title>Home Page</title></head>
<body id="body">
<div>
<p>Logged in as</p>
<ul class="nof-session">
<li><a href="/user" rel="user" rev="resource" class="nof-user">sven</a></li>
</ul>
</div>
<div class="nof-section">
<p class="nof-section">Resources</p>
<ul class="nof-resources">
<li>
<a href="/services" rel="services" rev="resources" class="nof-resource">
Services
</a>
</li>
<li>
<a href="/specs" rel="specs" rev="resources" class="nof-resource">
Specifications (MetaModel)
</a>
</li>
<li>
<a href="/user" rel="user" rev="resources" class="nof-resource">
User (Security)
</a>
</li>
</ul>
</div>
</body>
</html>Note the use of class attributes to distinguish
the different types of properties. For example, the XPath expression
//a[@class='nof-resource']/@href will return the
links to all resources available. One of these -
/services - is the list of services, so lets look
at that next.
Note
Depending on feedback, the format of the XHTML may evolve in the future, eg to add in further class attributes.