Wednesday Aug 06, 2008

BBC using Jersey

A recent comment on a blog entry from Jon, a developer at the BBC, says:

Thought you might be interested to hear that here at the BBC we now have a RESTFul JSR311 compliant webservice implemented using Jersey running with Jetty.

It is currently for internal use only but is part of an editorial toolset that Sports Journalists are using.

Nice, great news Jon! Maybe in some modest way Jersey will be contributing to the reporting of the Olympics :-)

Monday Jul 16, 2007

BBC Web API (beta)

Recently i took a look a the BBC Web API as i was curious to see how "webby" and RESTful or not it was.

In the RESTful Web services book Leonard and Sam, in section 1.5, provide some descriptions of competing Web service architectures. One architecture described (in section 1.5.3) is the REST-RPC hybrid architecture and although the documentation for the API makes no claims whether it be RESTful or RCPful or not i think the API fits firmly into the REST-RPC hybrid category.

The following is the URI used to GET the information of the BBC One channel:

http://www0.rdthdo.bbc.co.uk/cgi-perl/api/query.pl?method=bbc.channel.getInfo&channel_id=BBCOne&format=simple

Note the scoping information in the URI, as the query parameter method, but also the method information in the URI too using the same query parameter:

method=bbc.channel.getInfo.

One way to find out that something is not quite as RESTful as it can be is lop off all the query parameters and perform a GET on the URI and see if it results in an error. If an error occurs it can be an indication of an RPC-based architecture that is focused on URIs as endpoints.

Since the BBC Web API is read only it can be considered RESTful. But, as soon one moves to a read/write API (for example the BBC could offer a way for a user to annotate programs or post/delete comments) then things can start to get problematic (like using GET for deletion).

Furthermore, IMHO, URIs for REST-RPC hybrid architecture are fairly ugly. They tend to become cleaner and more intuitive if the scoping information is placed in the URI path, and therefore cooler. In fact it is very easy to implement the BBC Web API using the JSR 311 API and turn it into a cooler more RESTful Web service.

Consider the channel package that has three methods:

  1. bbc.channel.getInfo
  2. bbc.channel.getLocations
  3. bbc.channel.list

Instead the following URI paths could be used (respectively):

  1. channel/{id} 
  2. channel/{id}/locations
  3. channel 

and an example URI could be:

http://www0.rdthdo.bbc.co.uk/api/channels/BBCOne?format=simple

Notice that the method and channel_id parameters are no longer required. In JSR 311 we could write the following resource to support channels:

@UriTemplate("channel")
class ChannelResource {
    @HttpMethod
    Channels getList(@QueryParam("format") String format) { ... }

    @UriTemplate("{id}")
    @HttpMethod
    Channel getInfo(@QueryParam("format") String format,
        @UriParam("id"} int channelId) { ... }

    @UriTemplate("{id}/locations")
    @HttpMethod
    Locations getLocations(@QueryParam("format") String format,
        @UriParam("id"} int channelId) { ... }
}

assuming that Channels/Channel/Locations types are serializable by the 311 runtime. The same pattern can apply for genre, group and programme packages. The resource could be further improved by removing the query parameter format and instead using content types:

@UriTemplate("channel")
class ChannelResource {
@ProduceMime("application/simpletv+xml")
    @HttpMethod
    Channels getList() { ... }

         @ProduceMime("application/tvanytime+xml")
@HttpMethod
Channels getList() { ... }

...

     }

The 311 expert group is also considering support for the following:

@UriTemplate("channel")
@ProduceMime(["application/simpletv+xml", 
    application/tvanytime+xml"])
class ChannelResource {
    @HttpMethod
    Channels getList() { ... }

...

     }

such that the serializer for Channels is capable of understanding how to serialize in both the simple and TV-Anytime representations, and thereby, reducing the duplication of HTTP methods. While on the topic of the representations... unfortunately the API is missing an important REST constraint, which is "hypermedia is the engine of application state" or more concisely "connectedness", but to get into that detail requires another blog entry.

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