Why would I use restfulie?

1. Easy —> writing hypermedia aware resource based clients
2. Easy —> hypermedia aware resource based services
3. Small → it’s not a bloated solution with a huge list of APIs
4. HATEOAS —> clients you are unaware of will not bother if you change your URIs
5. HATEOAS —> services that you consume will not affect your software whenever they change part of their flow or URIs

Could you compare it with other REST related APIs?

Restfulie was the first API trying to somehow implement Jim Webber point of view on how RESTFul systems use hypermedia as the way to lead your client’s path through a business process.

Therefore Restfulie is unique in its feature set when compared to other (JAX-RS) based implementations: looking for simple code and favoring conventions over manual configurations when creating hypermedia aware system. Restfulie also handle content negotiation and its client implements cache and other set of features unsupported so far in other frameworks.

According to Richardson Maturity Model , systems are only to be called RESTFul if they support this kind of state flow transition through hypermedia content contained within resources representations:

Java or Ruby

One minute examples

Client side

The client side code allows you to hide http-protocol specifics if required, while allowing you to re-configure it when needed.
Example on accessing a resource and its services through the restfulie API:

Order order = new Order();
// place the order
order = service("http://www.caelum.com.br/order").post(order);
// cancels it
resource(order).getRelation("cancel").execute();

Server side

This is a simple example how to make your state changes available to your resource consumers:

By default, Restfulie serializes all primitive, String and enum types. In order to serialize child elements, one has pre-configure Restfulie. This is
the typical usage-pattern applications will face while using restfulie:

The entire serialization process can be configured either through the Resources interface’s methods or using *XStream*’s explicit configuration.

Caching

Most REST frameworks will not help the developer providing etags, last modified and other cache related headers.

Meanwhile, in the server side, Restfulie might add extra headers to handle last modified, etag and max age situations that will improve response time and avoid useless bandwidth consumption. In order to benefit from such cache characteristics, simply implement the RestfulEntity interface.

Accessing all possible transitions

One can access all possible transitions for an object by invoking a resource’s getRelations method:

List<Relation> relations = resource(order).getRelations();

While typical level 2 frameworks will only provide a statically, compilation time checked, relation/transition invocation, Restfulie allows clients/bots to adapt to REST results, giving your clients even less coupling to your services protocol.

HTTP verbs

By default, restfulie uses a well known table of defaults for http verb detection according to the rel element:

destroy, cancel and delete send a DELETE request

update sends a PUT request

refresh, reload, show, latest sends a GET request

other methods sends a POST request

If you want to use a custom http verb in order to send your request, you can do it:

More info

Once you have found the entry point you want to use (retrieving a resource or creating one), the javadoc api is a resourcefull place for more info.

Server side usage

The default way to use Restfulie is to define the getRelations method in your resource. The method receives a Restfulie instance (server side version) which allows you to dsl-like create transitions. In order to do that, given a Restfulie object, invoke the transition method with your rel name and the relative controller action:

Relation/Transition invocation

By using the @Transition to annotate your method, Restfulie will automatically load the order from the database and check for either 404 (object not found), 405 (method not allowed), 409 (conflict: transition is not allowed for this resource’s state) and 406 (content negotiation failed).

This is one of the advantages of using Restfulie over other level 2 Rest frameworks. By supporting hypermedia content and handling transitions out of the box, Restfulie creates a new layer capable
of helping the server to deal with unexpected states.

2. Usually the getRelations method would check the resource state in order to coordinate which transitions can be executed:
So add the getRelations method returning an array of possible transitions/relations:

You are ready to go. Create a new order and access it through your /order/id path.
The best way to start is to download the sample application and go through the OrderingController and Order classes.

Content negotiation

While most REST frameworks only support rendering xml out of the box, Restfulie already provides (through VRaptor and Spring) xml, xhtml and json representations of your resource. You can add new serializers as required. In order to take
content negotiation into play, simply use VRaptor’s representation() renderer:

Creating relations to other servers

Note that you can either create relations or transitions. We suggest clients to only use relations, but for clear semantics in some servers, you might want to invoke control.transition.

Accepting more than one argument

While typical JAX-RS services will deserialize your request body into your method argument and require you to retrieve extra URI information through the requested URI, Restfulie accepts one core parameter (based on its alias) and extra parameters to be extracted through the URI itself:

Parameter support is provided through VRaptor, so Iogi and Paranamer support is already built-in.

Asynchronous Request

To make an asynchronous request, you can use getAsync, postAsync, putAsync or deleteAsync methods. For that, you must provide a RequestCallback instance with a callback method implementation (the code to be executed when the response comes), like this:

XStream is the most famous java serialization tool around with support both to json and xml while VRaptor (as Rails) supplies a reverse URI lookup system upon its controller which provides a way to identify URI’s from well defined transitions.