netzooid

Since the cat is out of the bag, I figured I’d blog about the CXF (incubating) REST support a little as Apache Confluence seems to be down and I can’t write docs there…

One of the reasons I held off on REST support for XFire was that I wanted to do real support for REST style service. Not just this POST/GET crap that people claim as REST style. This means being able to map arbitrary URI/VERB combinations to services and their operations.

Lets say I want to build an HTTP service that shares and manipulates customer data. The first thing I might want to do is create a URI that returns a document of all the customers in my database. In CXF this would be done like so:

@Get @HttpResource(location="/customers") List getCustomers();

The @Get annotation maps the operation to the GET verb and the @HttpResource maps it to a URI. The List gets sent off the databinding implementation you’re using and will be serialized as a document. So far very simple!

Now lets say I want to pull down a specific customer, from /customers/ID:

@Get @HttpResource(location="/customers/{id}") Customer getCustomers(GetCustomer getCustomer);

The major new concept in this example is URI templates. The GetCustomer object has a single property named “id”. The URI parameters get mapped to the XML document according to its schema and the WSDL 2 rules. So CXF will actually synthesize an incoming XML document like this:

<customer><id>{id here}</id></customer>

Lets move on to a more complex example – a PUT operation which updates the customer:

@Put  @HttpResource(location="/customers/{id}") Customer updateCustomer(Customer customer);

Instead of synthesizing a document this time, we’re actually merging the URI parameters into the incoming document. This means {id} will get mapped to the /customer/id of the incoming customer document!

For a final example, lets look at adding a customer:

@Post @HttpResource(location="/customers") void addCustomer(Customer customer);

This will allow users to do a POST to the /customers URI with their document and add it to the collection of customers contained there.

And thats our REST support in a nutshell. A couple closing thoughts:

• You can create services in a true REST style with CXF. We support POST, PUT, GET, and DELETE as well as mapping arbitrary URIs.
• You can take existing services and make them REST easily by simply annotating them.
• These annotations are located over at the Java Rest Annotations project at the Codehaus. The idea is that in addition to CXF using them, web frameworks or other projects may want to use them as well. So have it at if you’re interested!
• REST is cool!

You can find the CXF sources here (sorry no release quite yet…), an example service here, and example unit test here. And for those of you wondering whats coming next:

• Support for HTTP headers. In my last POST example I think you’d really want to return the new ID of the customer so the user could then know to go to /customers/ID and find their new document there. This is fairly trivial to do.
• Client support
• A non annotation way of exposing services (probably an XML document)
• Support for non XML data, like JPEGs (yes CXF can do that!)
• WSDL 2 generation and code generation from WSDL 2

As always if you’d like to get involved, improve the HTTP binding, send your suggestions, etc, please pop on the mailing lists!

This entry was posted on Friday, October 27th, 2006 at 2:04 pm and is filed under Random.