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.

Comments:

Thanks for blog post. There's a lot to take in but I'll pass it on to the guys who actually wrote the API, if they haven't already seen it.

Posted by Ian Forrester on July 16, 2007 at 06:14 PM CEST #

Ian, thanks. I hope i did not come across as too negative, i should have said that i think it great that the BBC is experimenting with opening up data and making it accessible over the Web.

Posted by Paul Sandoz on July 17, 2007 at 10:37 AM CEST #

Paul,

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.

You might remember my name from some of the posts on the Jersey user forum earlier in the year and I believe you met one of my colleagues at the recent Jazoon conference in Zurich.

Anyway thanks for the help and maybe at some point you can add some comments about our new api to your blog :)

Jon

Posted by Jonathan Cook on August 01, 2008 at 11:08 AM CEST #

Hi Jon,

Wonderful news, i was really happy when your colleague informed me :-)

I will write a blog this week. Do you have any publicly accessible information on the new API?

Paul.

Posted by Paul Sandoz on August 04, 2008 at 06:20 AM CEST #

Hi Paul,

Will try to get something to you for next week. Hope that is OK

Jon

Posted by Jonathan Cook on August 06, 2008 at 05:29 PM CEST #

Post a Comment:
Comments are closed for this entry.
About

sandoz

Search

Archives
« July 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
31
  
       
Today