Automatic resource link discovery with RESTEasy and Atom links

This article describes how to use RESTEasy to inject Atom links in your resource representations, in order to secure your /editorials/tags/rest[RESTful] web services clients, and produce more RESTful web services with link auto-discovery.

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:

Table 1. Table 8.1. Maven artifact for Atom link injection
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:

Table 2. Table 8.2 ¶ `@LinkResource` parameters
Parameter	Type	Function	Default
value	`Class`	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 `Response` or `Collection` types, they need to be explicitly specified.
rel	`String`	The Atom link relation	list For `GET` methods returning a `Collection` self For `GET` methods returning a non-`Collection` remove For `DELETE` methods update For `PUT` methods add For `POST` methods

[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:

Table 3. Table 8.3. ¶ `@LinkResource` URI template parameter
Parameter	Type	Function	Default
pathParameters	`String[]`	Declares a list of UEL expressions to obtain the URI template values.	Defaults to using `@XmlID` and `@ParentResource` annotations to extract the values from the model.

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.

Table 4. Table 8.4. ¶ `@LinkResource` security restrictions
Parameter	Type	Function	Default
constraint	`String`	A UEL expression which must evaluate to true to inject this method’s link in the response entity.	Defaults to using `@RolesAllowed` from the JAX-RS method.

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();