Automatic resource link discovery with RESTEasy and Atom links
Of resources and links
When doing RESTful web services, there’s always a big debate when it comes to linking resources together. The non-RESTful way of doing things is to define URLs, hand them over to the client and call it the API. But the real RESTful way is to document your resources, a vocabulary of relations to link them with one another, and insert links with their relations inside your resources that indicate where sub-resources, related resources, and operations are located. Example of link relations include “update this resource” or “list of comments for this resource”.
This process is self-discovery, just like the good old web, which is what REST is modeled on. Even then some people put links in the HTTP response headers — which is better because it allows you to parse the links without parsing the response, while others prefer to put them directly on the resource representations — which allows more fine-grained links, and the ability to have links on multiple resources. Here is an example of such a link annotated with a relation:
<atom:link href="http://localhost/books" rel="list"/>
Security on the client side
For a recent customer project, we needed to find a way to secure a RESTful client interface, which turned out to be quite a shift from the usual server-side-minded way of handling security. Let me explain. In Seam or Play!, the server executes a template (of sorts) which builds the HTML page that the user is going to receive. On the server, we look at the current user permissions and only give him links to actions he is allowed to execute, to pages he is allowed to view:
<h:commandLink action="#{Controller.deleteBook(book)}"
rendered="#{s:hasPermission(book, 'delete')}">Delete Book</h:commandLink>
But for this particular project we were building a very AJAXy table viewer with inline editing. So we had a JavaScript widget which handled data coming in from REST web services. Our pages were not server-generated, but just plain-old very efficient HTML pages, with very dynamic content. Since every table entry could have different permissions, and the list of entries were not known when the table’s HTML page left the server (it got in later via AJAX), it was impossible to use traditional server-side templating to secure actions.
While the real security checks are done in the REST server side, since the clients can always be bypassed, there has to be a level of security filtering on the client to hide actions the user is not allowed to perform (since they would fail should he try them, because of server-side security).
Links as a security measure
The most RESTful way of doing such things is to let our table widget
discover the permissions for every row, and for the table itself. And
links are a great way to do this: simply specify a number of link
relations as part of the API (the documentation of your REST services,
which is mostly about resources) such as add
or remove
, and include
those links whenever the user has the permission to do the action. The
table widget then only has to see if entries have an update
link to
know if the line is editable or not, and modify the UI accordingly.
There are two languages where links with relations are used: HTML and Atom. For some reason, Atom links are the ones most referred to when talking about REST, so that’s the term we will be using. Those are just a normalisation of how to write links and relations.
Links in RESTEasy
RESTEasy already had support for Link headers (which contain Atom link equivalents) for a while, but for this we needed resource-level links, and not response-level links, since our responses contained more than one resource on multiple levels.
Did you know Lunatech Labs has a RESTEasy committer? Stéphane Épardaud has been a long time RESTEasy user (since before the first release really), and contributed to several modules such as OAuth and the JavaScript Client API (in SVN for a while but not released yet). With several experimental versions he finally got somewhere and produced an API which is good enough to be added to RESTEasy, and is in fact already used in production on our customer project.
Now when we get the following resource on our client, we know we are
allowed to update
but not remove
(because the relation is absent)
the given book:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book xmlns:atom="http://www.w3.org/2005/Atom" title="foo" author="bar">
<atom:link href="http://localhost/book/foo" rel="self"/>
<atom:link href="http://localhost/book/foo" rel="update"/>
</book>
The following article is in fact the very documentation for this module, that will appear in the 2.0 release of RESTEasy.
[d0e541]# RESTEasy allows you to inject Atom links directly inside the entity objects you are sending to the client, via auto-discovery.
Warning
This is only available when using the Jettison or JAXB providers (for JSON and XML).
The main advantage over Link headers is that you can have any number of Atom links directly over the concerned resources, for any number of resources in the response. For example, you can have Atom links for the root response entity, and also for each of its children entities.
##Configuration
[d0e554]# There is no configuration required to be able to inject Atom links in your resource representation, you just have to have this maven artifact in your path:
Group | Artifact | Version |
---|---|---|
org.jboss.resteasy |
resteasy-links |
2.0-beta-2 |
##Your first links injected
[d0e586]# You need three things in order to tell RESTEasy to inject Atom links in your entities:
-
[d0e586]# Annotate the JAX-RS method with
@AddLinks
to indicate that you want Atom links injected in your response entity. -
[d0e586]# Add
RESTServiceDiscovery
fields to the resource classes where you want Atom links injected. -
[d0e586]# Annotate the JAX-RS methods you want Atom links for with
@LinkResource
, so that RESTEasy knows which links to create for which resources.
[d0e586]# The following example illustrates how you would declare everything in order to get the Atom links injected in your book store:
@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {
@AddLinks
@LinkResource(value = Book.class)
@GET
@Path("books")
public Collection<Book> getBooks();
@LinkResource
@POST
@Path("books")
public void addBook(Book book);
@AddLinks
@LinkResource
@GET
@Path("book/{id}")
public Book getBook(@PathParam("id") String id);
@LinkResource
@PUT
@Path("book/{id}")
public void updateBook(@PathParam("id") String id, Book book);
@LinkResource(value = Book.class)
@DELETE
@Path("book/{id}")
public void deleteBook(@PathParam("id") String id);
}
[d0e586]# And this is the definition of the Book resource:
@Mapped(namespaceMap =
@XmlNsMap(jsonName = "atom",
namespace = "http://www.w3.org/2005/Atom"))
@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class Book {
@XmlAttribute
private String author;
@XmlID
@XmlAttribute
private String title;
@XmlElementRef
private RESTServiceDiscovery rest;
}
[d0e586]# If you do a GET /order/foo you will then get this XML representation:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book xmlns:atom="http://www.w3.org/2005/Atom" title="foo" author="bar">
<atom:link href="http://localhost/books" rel="list"/>
<atom:link href="http://localhost/books" rel="add"/>
<atom:link href="http://localhost/book/foo" rel="self"/>
<atom:link href="http://localhost/book/foo" rel="update"/>
<atom:link href="http://localhost/book/foo" rel="remove"/>
</book>
[d0e586]# And in JSON format:
{
"book":
{
"@title":"foo",
"@author":"bar",
"atom.link":
[
{"@href":"http://localhost/books","@rel":"list"},
{"@href":"http://localhost/books","@rel":"add"},
{"@href":"http://localhost/book/foo","@rel":"self"},
{"@href":"http://localhost/book/foo","@rel":"update"},
{"@href":"http://localhost/book/foo","@rel":"remove"}
]
}
}
##Customising how the Atom links are serialised
[d0e626]# Because the RESTServiceDiscovery
is in fact a JAXB type
which inherits from List
you are free to annotate it as you want to
customise the JAXB serialisation, or just rely on the default with
@XmlElementRef
.
##Specifying which JAX-RS methods are tied to which resources
[d0e640]# This is all done by annotating the methods with the
@LinkResource
annotation. It supports the following optional
parameters:
Parameter | Type | Function | Default |
---|---|---|---|
value |
|
Declares an Atom link for the given type of resources. |
Defaults to the entity body type (non-annotated parameter), or the
method’s return type. This default does not work with |
rel |
|
The Atom link relation |
|
[d0e640]# You can add several @LinkResource
annotations on a single
method by enclosing them in a @LinkResources
annotation. This way you
can add links to the same method on several resource types. For example
the /order/foo/comments
operation can belongs on the Order
resource
with the comments
relation, and on the Comment
resource with the
list
relation.
##Specifying path parameter values for URI templates
[d0e780]# When RESTEasy adds links to your resources it needs to
insert the right values in the URI remplate. This is done either
automatically by guessing the list of values from the entity, or by
specifying the values in the @LinkResource
pathParameters
parameter.
##Loading URI template values from the entity
[d0e791]# URI template values are extracted from the entity by
annotating a field or Java Bean property with the @XmlID
annotation.
If there are more than one URI template value to find, we try to find
the parent of the entity in a field of Java Bean property annotated with
@ParentResource
. The list of @XmlID
values extracted up every
@ParentResource
is then reversed and used as the list of values for
the URI template.
##For example, let’s consider the previous Book example, and a list of comments:
@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class Comment {
@ParentResource
private Book book;
@XmlElement
private String author;
@XmlID
@XmlAttribute
private String id;
@XmlElementRef
private RESTServiceDiscovery rest;
}
Given the previous book store service augmented with comments:
@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {
@AddLinks
@LinkResources({
@LinkResource(value = Book.class, rel = "comments"),
@LinkResource(value = Comment.class)
})
@GET
@Path("book/{id}/comments")
public Collection<Comment> getComments(@PathParam("id") String bookId);
@AddLinks
@LinkResource
@GET
@Path("book/{id}/comment/{cid}")
public Comment getComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
@LinkResource
@POST
@Path("book/{id}/comments")
public void addComment(@PathParam("id") String bookId,
Comment comment);
@LinkResource
@PUT
@Path("book/{id}/comment/{cid}")
public void updateComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId,
Comment comment);
@LinkResource(Comment.class)
@DELETE
@Path("book/{id}/comment/{cid}")
public void deleteComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
}
Whenever we need to make links for a `Book` entity, we look up the ID in the `Book`'s `@XmlID` property. Whenever we make links for `Comment` entities, we have a list of values taken from the `Comment`'s `@XmlID` and its `@ParentResource`: the `Book` and its `@XmlID`.
For a `Comment` with `id` `"1"` on a `Book` with `title` `"foo"` we will therefore get a list of URI template values of `{"foo", "1"}`, to be replaced in the URI template, thus obtaining either `"/book/foo/comments"` or `"/book/foo/comment/1"`.
Specifying path parameters manually
If you do not want to annotate your entities with @XmlID
and @ParentResource
, you can also specify the URI template values
inside the @LinkResource
annotation, using Unified Expression Language
expressions:
Parameter | Type | Function | Default |
---|---|---|---|
pathParameters |
|
Declares a list of UEL expressions to obtain the URI template values. |
Defaults to using |
The UEL expressions are evaluated in the context of the
entity, which means that any unqualified variable will be taken as a
property for the entity itself, with the special variable this
bound
to the entity we’re generating links for.
The previous example of Comment
service could be declared
as such:
@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {
@AddLinks
@LinkResources({
@LinkResource(value = Book.class, rel = "comments",
pathParameters = "${title}"),
@LinkResource(value = Comment.class,
pathParameters = {"${book.title}", "${id}"})
})
@GET
@Path("book/{id}/comments")
public Collection<Comment> getComments(@PathParam("id") String bookId);
@AddLinks
@LinkResource(pathParameters = {"${book.title}", "${id}"})
@GET
@Path("book/{id}/comment/{cid}")
public Comment getComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
@LinkResource(pathParameters = {"${book.title}", "${id}"})
@POST
@Path("book/{id}/comments")
public void addComment(@PathParam("id") String bookId,
Comment comment);
@LinkResource(pathParameters = {"${book.title}", "${id}"})
@PUT
@Path("book/{id}/comment/{cid}")
public void updateComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId,
Comment comment);
@LinkResource(Comment.class,
pathParameters = {"${book.title}", "${id}"})
@DELETE
@Path("book/{id}/comment/{cid}")
public void deleteComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
}
Securing entities
You can restrict which links are injected in the resource
based on security restrictions for the client, so that if the current
client doesn’t have permission to delete a resource he will not be
presented with the "delete"
link relation.
Security restrictions can either be specified on the
@LinkResource
annotation, or using RESTEasy and EJB’s security
annotation @RolesAllowed
on the JAX-RS method.
Parameter | Type | Function | Default |
---|---|---|---|
constraint |
|
A UEL expression which must evaluate to true to inject this method’s link in the response entity. |
Defaults to using
|
Extending the UEL context
We’ve seen that both the URI template values and the
security constraints of @LinkResource
use UEL to evaluate expressions,
and we provide a basic UEL context with access only to the entity we’re
injecting links in, and nothing more.
[d0e999]# If you want to add more variables or functions in this
context, you can by adding a @LinkELProvider
annotation on the JAX-RS
method, its class, or its package. This annotation’s value should point
to a class that implements the ELProvider
interface, which wraps the
default ELContext
in order to add any missing functions.
For example, if you want to support the Seam annotation
s:hasPermission(target, permission)
in your security constraints, you
can add a package-info.java
file like this:
@LinkELProvider(SeamELProvider.class)
package org.jboss.resteasy.links.test;
import org.jboss.resteasy.links.*;
[d0e999]# With the following provider implementation:
package org.jboss.resteasy.links.test;
import javax.el.ELContext;
import javax.el.ELResolver;
import javax.el.FunctionMapper;
import javax.el.VariableMapper;
import org.jboss.seam.el.SeamFunctionMapper;
import org.jboss.resteasy.links.ELProvider;
public class SeamELProvider implements ELProvider {
public ELContext getContext(final ELContext ctx) {
return new ELContext() {
private SeamFunctionMapper functionMapper;
@Override
public ELResolver getELResolver() {
return ctx.getELResolver();
}
@Override
public FunctionMapper getFunctionMapper() {
if (functionMapper == null)
functionMapper = new SeamFunctionMapper(ctx
.getFunctionMapper());
return functionMapper;
}
@Override
public VariableMapper getVariableMapper() {
return ctx.getVariableMapper();
}
};
}
}
And then use it as such:
@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {
@AddLinks
@LinkResources({
@LinkResource(value = Book.class, rel = "comments",
constraint = "${s:hasPermission(this, 'add-comment')}"),
@LinkResource(value = Comment.class,
constraint = "${s:hasPermission(this, 'insert')}")
})
@GET
@Path("book/{id}/comments")
public Collection<Comment> getComments(@PathParam("id") String bookId);
@AddLinks
@LinkResource(constraint = "${s:hasPermission(this, 'read')}")
@GET
@Path("book/{id}/comment/{cid}")
public Comment getComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
@LinkResource(constraint = "${s:hasPermission(this, 'insert')}")
@POST
@Path("book/{id}/comments")
public void addComment(@PathParam("id") String bookId,
Comment comment);
@LinkResource(constraint = "${s:hasPermission(this, 'update')}")
@PUT
@Path("book/{id}/comment/{cid}")
public void updateComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId,
Comment comment);
@LinkResource(Comment.class,
constraint = "${s:hasPermission(this, 'delete')}")
@DELETE
@Path("book/{id}/comment/{cid}")
public void deleteComment(@PathParam("id") String bookId,
@PathParam("cid") String commentId);
}
Resource facades
Sometimes it is useful to add resources which are just
containers or layers on other resources. For example if you want to
represent a collection of Comment
with a start index and a certain
number of entries, in order to implement paging. Such a collection is
not really an entity in your model, but it should obtain the "add"
and
"list"
link relations for the Comment
entity.
This is possible using resource facades. A resource facade
is a resource which implements the ResourceFacade
interface for the
type T
, and as such, should receive all links for that type.
Since in most cases the instance of the T
type is not
directly available in the resource facade, we need another way to
extract its URI template values, and this is done by calling the
resource facade’s pathParameters()
method to obtain a map of URI
template values by name. This map will be used to fill in the URI
template values for any link generated for T
, if there are enough
values in the map.
Here is an example of such a resource facade for a collection of `Comment`s:
@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class ScrollableCollection implements ResourceFacade<Comment> {
private String bookId;
@XmlAttribute
private int start;
@XmlAttribute
private int totalRecords;
@XmlElement
private List<Comment> comments = new ArrayList<Comment>();
@XmlElementRef
private RESTServiceDiscovery rest;
public Class<Comment> facadeFor() {
return Comment.class;
}
public Map<String, ? extends Object> pathParameters() {
HashMap<String, String> map = new HashMap<String, String>();
map.put("id", bookId);
return map;
}
}
This will produce such an XML collection:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection xmlns:atom="http://www.w3.org/2005/Atom" totalRecords="2" start="0">
<atom.link href="http://localhost/book/foo/comments" rel="add"/>
<atom.link href="http://localhost/book/foo/comments" rel="list"/>
<comment xmlid="0">
<text>great book</text>
<atom.link href="http://localhost/book/foo/comment/0" rel="self"/>
<atom.link href="http://localhost/book/foo/comment/0" rel="update"/>
<atom.link href="http://localhost/book/foo/comment/0" rel="remove"/>
<atom.link href="http://localhost/book/foo/comments" rel="add"/>
<atom.link href="http://localhost/book/foo/comments" rel="list"/>
</comment>
<comment xmlid="1">
<text>terrible book</text>
<atom.link href="http://localhost/book/foo/comment/1" rel="self"/>
<atom.link href="http://localhost/book/foo/comment/1" rel="update"/>
<atom.link href="http://localhost/book/foo/comment/1" rel="remove"/>
<atom.link href="http://localhost/book/foo/comments" rel="add"/>
<atom.link href="http://localhost/book/foo/comments" rel="list"/>
</comment>
</collection>
Conclusion
RESTEasy is now able to generate Atom links for resources based on your JAX-RS service declaration, with simple default settings and powerful customisations for URI template variable resolving, security checks, and UEL extension points. This is a feature that allowed us to easily and RESTfully customise our client’s user interfaces based on security permissions that only the server knows.
Of course, this is only the beginning, because jax-doclets support is coming soon, as well as support in the JavaScript Client API, which should allow you do do this soon:
// this line is already supported
var book = BookStore.getBook("foo");
book.title = "bar";
// This would then use the Atom link relations:
book.update();
// or
book.remove();