J1 Session on RESTful Web services
By sandoz on May 14, 2007
Marc, Rico (Roderico) and I presented on the Java API for RESTful Web services. (I will post a link to the slides once i work out what my password is to access them!)
Our timing was spot on and the demo went without a hitch. I got the impression that the session was generally well received, there was no mass exodus which is always a good sign (although i will hold judgment until we get the review feedback...).I wanted to get across the following main points:
- This is an API to help build RESTful Web services. A protocol, like HTTP, an API, such as JSR-311, and set of Java classes using 311 and HTTP are necessary but not sufficient for building a RESTful Web service. The fourth, and most important part, is the application of the REST architectural style to the protocol, the API and the Web service. The HTTP protocol can be used in a non-RESTful way (see WS-\*) and so can any API that provides good support for HTTP. With 311 we want to provide 'a path of least resistance' that encourages developers to think of resources (identified by URIs), methods (with constraints) and representations (identified by media types) and thus the developer is hopefully better positioned to apply the REST architectural style. In this respect the 311 API is no magic bullet and it will require some discipline on the part of the developer. However, I hope (in a modest way) a developer using this API will be more productive when building RESTful Web services in Java.
- Sun has in the past been rather good at enabling developers to solve the hard problems but as a result has made solving the simple problems hard. We want to ensure that (shamelessly copying the perl mantra) that this API makes solving the simple problems brain-dead-simple and the hard problems possible. Furthermore, in this respect, we don't want to pull the rug from underneath the developers and make the solving of some problems impossible, which is why it is very important to have full low-level access to HTTP stuff (like what the servlet API provides).
- When developing RESTful Web services it would be a mistake to hide the network and HTTP. The Fallacies of Distributed Computing provide very good advice. HTTP needs to be viewed as an application protocol (rather than a transport protocol) for the transfer of representations and thus it would be a mistake not only to hide the network but the HTTP semantics in the 311 programming model. For example, the HTTP method GET is considered a safe method:
the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval
thus the developer should be aware of this important constraint. Further more, the GET method can change to a conditional GET method that may require application specific information (entity tag and last modified date) to calculate when an entity is required to be transferred in a response.
- The API places no restrictions on the choice of MIME type or Java type for an entity of an HTTP request or a representation of an HTTP response (in general many different types of entities can be consumed and many different types of representations can be produced by a resource). A common set of Java types will be required to be supported by a 311 runtime, for example JAXB-based types, but a developer could easily use the XOM API (in conjunction with the Nux toolkit), or alternatively JSONObject or indeed a Java object model for RDF (using Sommer) with the N3 syntax.
Unfortunately for this presentation we did not have time to drill down into details. One area that requires more discussion in the expert group (and would be good to present on) is that of mapping the URI path hierarchy to Java classes, see here for an example of what i am getting at. Nor did we have much time to get into a fundamental part of the REST architectural style: "hypermedia is the engine of application state" (the demo highlighted it a bit in the way entity classes are converted to JAXB classes, namely how entity relationships are converted to URIs). This last one is tricky to embed in an API but i think good first class support for URIs and URI templates in conjunction with the URI path hierarchy mapping is fundamental and maybe sufficient for a non-imposing solution that can help foster more innovation in this area.
In general, when applying the REST architectural style, the server-side programming model for RESTful Web services is different to that of RPC-based Web services. It encourages a "wire-centric" view and aspects of the 311 API are starting to reflect this.