Wednesday Dec 12, 2007

Dynamic WADL generation in Jersey

Current stable versions of Jersey require an awkward tool time step to identify the set of root resource classes and then generate a WADL document, from that set, that is accessible from the Web application.

For the next release, 0.5, everything will be dynamic. And we have just finished adding dynamic WADL support to the trunk. So the same URI, <base URI>/application.wadl,  to access the WADL of the Web application is supported but no tool-time configuration is required. There is a runtime requirement that the JAXB jars be in the class path, if not then WADL support is turned off but the Web application will still work.

In addition there is experimental support for GETing the WADL of a specific resource. At deployment the runtime only knows about root resource classes but a Web application can dynamically return other resources. This allows a client to GET WADL for such resources enabling the client to "WADL" through the resources :-) I like this approach, it fits more closely with the view of WADL as hypermedia and using WADL in a much more loosely coupled way rather than a way to describe the whole Web application.

Currently WADL is obtained by a client performing a GET request on a URI and setting the Accept header to include the media type "application/vnd.sun.wadl+xml". I am not sure i like this approach as it can interfere with application specific GET methods (it is implemented so application specific GET methods take priority, thus WADL may not always be returned).



Two other approaches may be more appropriate:

  1. Return WADL as the representation of HTTP OPTIONS response. The OPTIONS method is automatically supported to return the allowed HTTP methods in the Allow response header.
  2. Return WADL using a sub-resource, say "/application.wadl".
Approach 1 seems kind of natural and is the least intrusive but i am not sure how widely supported OPTIONS is by clients. Approach 2 is less intrusive that the currently implemented approach but it does require the client to know something specific to construct the WADL URI.

Monday Nov 05, 2007

URLs to the fore

David is right, put the URLs to the fore of any documentation of a RESTful API. The first thing i did when looking at the OpenSocial Data API documents was scan them to see what the URL patterns were. David provides a useful summary.

In general i recommend creating tables with URI templates, methods supported, content types produced/consumed and response codes returned. For extra bonus-points provide XPath expressions for XML representations that highlight the connected relationship to other resources. This really helps developers implementing the API and consumers. Or, use WADL with a style sheet as show by Mark Nottingham for the Yahoo news search.

About

sandoz

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today