Guilherme Silveira on Restfulie

Recorded at:

Bio Guilherme Silveira is the lead developer and training services coordinator at Caelum, Brazil, a company specialized in training and development, and involved in many open source projects like VRaptor, XStream, Hibernate, or Maven and creator of Restfulie, a Restful framework with implementations in Java and Ruby.

QCon is a conference that is organized by the community, for the community.The result is a high quality conference experience where a tremendous amount of attention and investment has gone into having the best content on the most important topics presented by the leaders in our community. QCon is designed with the technical depth and enterprise focus of interest to technical team leads, architects, and project managers.

The framework is about helping programmers to use hypermedia content while providing their resource representations to their clients and consuming those representations in the client-side by helping developers on the client-side to execute the transitions or execute the connections with the server-side.

JAX-RS is based on the specification from JSR and the idea is that JAX-RS is a little bit more verbose than Restfulie, that is the basic idea from Restfulie. Restfulie should be something small and something that just doesn't get into our way of coding or writing a code and the other key point is that it doesn't really help you so much, the other frameworks don't help you so much with the hypermedia content.

There are those 3 levels that some people talk about and the first idea is that URIs should identify resources. The second idea is to use HTTP verbs and some infrastructure from the HTTP or their web to provide your services or your resource implementation and the third idea would be something like using hypermedia links to provide a way for your client to interact with your system. For example if I have an order and I have to pay that order or do something I like, the order representation, the XML or JSON or whatever would contain hyperlinks to what can be done with that order; so instead of being such a pure data structure it will contain hyperlinks to the clients somehow giving a hand and saying: "Ok, from here you can do these" and guiding the clients on what he can do.

It helps both on the client-side and on the server-side also. On the server-side it helps by providing an easy way to add this hypermedia content. For example, in the Java version you have XStream as the basic serialization framework and it will provide a way to insert the hypermedia links within the XML or JSON representations. Meanwhile on the client side, in Ruby version for example, it helps you by dynamically recreating your objects and allowing you to invoke methods which represent those transitions in your resources lifecycle.

On the server-side there's can-something-methods should know whether these transitions are available according to their state, but at the client's side you should ask if the methods are available or not. Ruby allows you to ask whether the method is available or not, with their response to method, so I think that is enough for the user to know.

I think the main goal is to provide something easy and something just simple, that you can use in maybe just 5 minutes just start playing with it. So the Java version is a little bit more complicated because in the Rails world and the Ruby world we have basically most people using Rails and that's it. So we decide: "Ok, we are implementing it for Rails", so it's quite easy because I know that people are going to use the to-xml implementation of serialization from Rails and I know what is the basic controller because it's the Rails controller.

On the Java world it's completely different: we have JAXB, XStream and many other serialization processes, so I don't know which serialization process the user is going to use or he wants or he desires. And we don't know which MVC framework he is going to use, so it's a completely different world, if you are going to use Spring with Spring interceptors or whatever or if you are going to use some JSF-based framework or if you are going to use VRaptor or anything else. The basic implementation for Java right now is based on XStream as a serializations or deserialization API and based on VRaptor as the web framework right now. But it's available for someone to extend it and implement it for other frameworks and serialization processes.

Right now it's in the experimental phase; we are doing some work with Jim Webber and Ian Robinson's book. They have a couple of examples that we are trying to make working so far and the idea is to try to get people from the community who want to use it and get feedback from them, so we can know what we need to improve; that is the main idea.

There is a lot of documentation missing; we have to document on a lot of stuff. As you mentioned there is a lot of buzzwords in just the first phrases and that was just too intentional so the person would keep reading and see the examples and then get the documentation itself. So there is a lot of documentation missing both on Ruby and Java version, there is a lot of refactoring that should be done on Ruby code because the code was really basic. There is also the .NET version; we would really grateful if someone gives a hand on the .NET framework because we don't have anyone available to do that.

Jersey has for those who don't like some of the syntax problems that you have in some APIs, Jersey is somehow based on some static methods, some methods that you have to invoke that might get into your way. For example in the clients side you are going to write a lot of extra code or you are going to have extra classes due to JAXB or due to the nature of the code that you are going to invoke. This nature involves things such as HTTP -based classes or methods as I would say something as:" I want to post an order to this URI, but that is not exactly my domain.

My domain would be, I want to add this client to the list of clients from these projects; that should be the code that I want to write on my client side, I want your side to write order.pay() and that would be a remote invocation related to the transition of this from unpaid to paid; that would be the thing which would happen. With Jersey I would write something related to the URI, I would write something related to POST, I would write for the framework and not for my domain; I think that is something completely different compared to Restfulie.

It shouldn't be transparent for the user that there is no remote invocation. If we are invoking something on the remote server, we have to do something with the remote server. So there is the serialization process, there is the deserializing process and there is the remote invocation of something, there is something going on in the remote server and the user, the programmer should know that. So that is something that although it's going to get out of the user's way, the user still has to know about it of course. I think one of the key points would be that we just don't provide one way for the user to get an API and read: "OK, I have this list of invocations that I can do and these invocations I have to pass search arguments" and that's how it works. Instead I have something as an object, I actually see it as an object, that is one dumb point of view, and I iterate with that object which might be something else RPC. So I iterate with that object, so I would say: "Ok, this is the order that I have on the server side" so I would pay it.

Yes, it follows the conventions all over the place so otherwise I wouldn't get simpler right if I don't follow any conventions I have to configure everything, either by XML, annotations or some other way. So both on Rails we follow the conventions for Rails and on Java we follow some conventions for XStream and some conventions for VRaptor and that's it.

Yes, you can programmatically configure the request itself so if executing, for example, a post request, but I don't want to do a post or I don't want to do a patch, if I exists, you can do it on that specific request or you can pre-configure everything and then just use that instance, an immutable instance.

By having some conventions we can follow some paths as to modify our bytecode and implement or just modify or intercepting some calls and adding new behavior to those controllers which were already written. So for instance, in Jersey checking if an order exists, and if it doesn't exist give back 404, I would just by default get their order and if the order exists it invokes our method, if it doesn't exist it gives back 404 and I don't have to worry about it. So 404 is just a simple example, but we have also conflicts and other type of responses that I can implement by default just because you follow the conventions.

Yes. There is a lot of difference between the Java and Ruby version on the API itself, because we cannot do the same thing in Java that we do in Ruby, the open classes and open objects, everything is completely different. Some of the behavior that we added to the Java model over the client side is using Javassist in order to modify the bytecode and extend the classes and implement a new interface and using some tricks in order for the user to get access to a new API and an object that doesn't contain that API. So it works in a similar way but the API is completely different or somehow different.

There is enough difference on it so some people might prefer the one or might prefer the other. For instance in the Ruby version I would just invoke Order.pay(); in the Java version I cannot just add the pay() method to the Order class because it was compiled unless I have to invoke dynamic in the future. Meanwhile what I can do is I can do something as order or resource_order.transition_pay(), whatever; so the syntax is completely different.

Thanks... from QCon SFO day until today there were a lot of news: there is a C# client, Java and Ruby has evolved a lot, including more and more functionalities that are still not in JSR-311... moving forward to becoming rest someday?

Congratulations Guilherme! I don´t know you personally but I know about Caelum and feel quite happy to know that there are people who represent us (brazilians developers) very well! Congratulations again!