Options for responses to a successful Tag request
Chris Lowis
In the proposed RadioTAG specification (see the previous discussions
and sequence diagrams) following a successful Tag the TagService
responds to the device with an "OK" response.
I'd like to discuss some options for the format that response could
take, and see if the members of the list have any opinions or
preferences. In doing so I'm summarising some of the discussions I've
had on this topic with Andy and Sean.
We're considering a request of the form
POST /tag HTTP/1.1
Host: www.bbc.co.uk
token=ABC123&station=09700.ab.ab1.fm&time=123
** No response
The simplest response is no response. Here the client would have no
work to do in parsing or presenting information to the user, but for
that reason the device would not be able to present confirmation of
Tag creation to the listener.
** Respond with a 200 OK status code
HTTP/1.1 200 OK
Date: Thu, 24 Mar 2011 15:11:34 GMT
In RFC2616 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) a
200 status code indicates that a request has succeeded. There is also
provision, for POST requests, to return "an entity describing or
containing the result of the action". I'll consider some forms that
response could take below.
For this response the listener could at least have confirmation that
the Tag request was successful.
** Respond with a 201 CREATED status code
HTTP/1.1 201 CREATED
Date: Thu, 24 Mar 2011 15:11:34 GMT
Location: http://bbc.co.uk/tags/chrislo/1
A 201 created response could be returned. According to RFC2616 "the
response SHOULD include an entity containing a list of resource
characteristics and location(s) from which the user or user agent can
choose the one most appropriate." and the preferred place to return the
location is in the Location header.
Here we would have to return a URL for the newly-created Tag. As an
example above I've returned a URL that scopes the tag to my user name,
and I'd expect that a GET request to that URL would only succeed (in
the first instance) if accompanied by the Authorization Token. I could
imagine a system that allows some control over who can access my Tags
(possibly using OAuth).
What would be contained at the URL for the newly-created Tag would be
up to the broadcaster, but if we would like devices to do something
useful with the information (like display it to the user) we may have
to follow something like the formats discussed below for response
bodies.
** Respond with a 201 and some text in the body
HTTP/1.1 201 CREATED
Date: Thu, 24 Mar 2011 15:11:34 GMT
Location: http://bbc.co.uk/tags/chrislo/1
Chris Evans, Radio 2 Breakfast Show. Now playing: Adele - Someone
Like You.
Another option is to return, in the body of the response, some text
which relates to the Tag that has been created. In this case, a plain
text description of the Brand, Episode and Now Playing information.
This information could be simply displayed to the listener on a
limited-display device, and would require no standardisation of the
format of the response. We could, perhaps, suggest a maximum string
length and encoding.
On the other hand, it would be hard to do anything more sophisticated
on the device with such a simple format (such as display cover art, or
more information about a show or artist) without standardising on an
agreed format for the text.
** Respond with a 201 and some JSON in the body
HTTP/1.1 201 CREATED
Date: Thu, 24 Mar 2011 15:11:34 GMT
Location: http://bbc.co.uk/tags/chrislo/1
[
{"url": "http://www.bbc.co.uk/programmes/b00zl8x6",
"img": "http://www.bbc.co.uk/programmes/b00zl8x6.jpg",
"description" : "The Chris Evans Breakfast Show. Weekdays 0630-0900."},
{"url":
"http://www.bbc.co.uk/music/artists/cc2c9c3c-b7bc-4b8b-84d8-4fbd8779e493",
"img":
"http://static.bbc.co.uk/music/images/artists/234x132/cc2c9c3c-b7bc-4b8b-84d8-4fbd8779e493.jpg",
"description" : "Adele - Someone Like You."}]
To get around the problem of parsing meaningful information from the
body of the 201 response, we could return some JSON which included
information.
Here as an example I've decided to return an Array of JSON objects,
where each object contains some information associated with the Tag
time. Each object has a URL and Image and a Description. Simpler
devices could decide to just show the first description, while others
might provide a rotating display with images and links. We could also
consider defining a "type" for each object (track, episode etc.).
This approach, while powerful, has a "smell" about it somehow. Are we
straying to far by specifying the format of the response in this spec?
I'd appreciate thoughts on that.
** Respond with a 201 and some RDF/XML in the body
I thought I'd include this for completeness. We could return in the
body (and at the location header) some RDF which corresponds, for
example, to a particular ontology[1]. Here's some sample RDF for an
episode of Chris Evan's breakfast show, for example:
http://www.bbc.co.uk/programmes/b00zl8x6.rdf
This would have the advantage of not requiring an up-front
specification as we could leverage an existing one. Devices could also
be updated to support more elements and formats by changing their software.
The natural downside, of course, is in the complexity of both
authoring and parsing the RDF.
I'd be very interested in hearing some ideas from the list on this
subject, and also for someone to point out if I've missed any other
possible ways of responding to a Tag.
My personal feeling is that the 201 CREATED with a Location header and
no body is the cleanest and most 'RESTful' way to go, but it still requires
specification of a data format to be consumed at the resource URL if
we wish to support rich device presentations.
Cheers,
Chris
[1] A good choice might be the Programmes Ontology
http://www.bbc.co.uk/ontologies/programmes/2009-09-07.shtml
--
Dr. Chris Lowis
Software Engineer, BBC R&D Prototyping
Andy Buckingham (RadioDNS)
that the meta behind a tag may change over time. For example, at the
second the tag is captured against a live event it may be a breaking
news story with little or no information in the broadcasters systems
to populate against the event.
However, over time as the story develops it would be possible for the
broadcaster to go back and associate any tags within an elapsed time
frame with a news story about that event.
Therefore I'm a little anxious about returning actual meta in the
response body as it would tend to suggest you hit the web service, get
the meta and that's the end of the transaction.
I like the use of a 201 Created header, as we are "creating" a tagged
event. I also like the use of the Location: header to refer to a URL
to provide a URL that uniquely identifies the tagged event.
Beyond this I think if we begin to discuss devices with full colour
screens that may require richer image/description etc. we should
really revisit the concept of a "feed". This offers the benefit of
being able to use modified-since, expires headers and cache control to
regulate devices seeing if the meta is up-to-date. It provides a
resource that be queried to get the most recent data associated to a
tag, rather than just being a one time hit cached set of data. It also
means for users that have multiple devices associated with a single
user account we can return all tags across all devices so a tag made
on the kitchen radio would then be visible on the lounge radio and
vice versa.
I do think it might be worth using the return body to provide a user
surfacable text response to provide information on the specific of the
broadcasters implementation. Taking a leaf from the OAuth response
formats, I'd propose something like:
HTTP/1.1 201 Created
Location: http://www.capitalfm.com/tags/andybee/1234
{"description": "Tag received! Register to view tags at capitalfm.com/tags"}
Obviously, there is nothing stopping a service provider putting deeper
information in that response as per Chris' example:
{"description": "You tagged Adele - Rolling in the Deep. Register to
view tags anytime at capitalfm.com/tags"}
The simplicity means a manufacturer is only required to surface a
string on screen. We should probably apply a character limit of, say,
128 characters (the same as a DLS string) to ease the implementation
on simple devices.
A
--
Andy Buckingham
RadioTAG Application Team Lead
RadioDNS Project and Global Radio (UK)
t: +44 (0)117 900 5357
e: andy.bu...@radiodns.org
w: http://radiodns.org/
Follow the RadioDNS Project via Twitter: @radiodns
Chris Lowis
> I think it's important when considering a response to this the fact
> that the meta behind a tag may change over time. For example, at the
> second the tag is captured against a live event it may be a breaking
> news story with little or no information in the broadcasters systems
> to populate against the event.
Yes, that's a good point. In that sense it would be better to just
return a Location of the Tag resource and the format of the response to
a request for that resource would then reflect the time at which it was
accessed.
> However, over time as the story develops it would be possible for the
> broadcaster to go back and associate any tags within an elapsed time
> frame with a news story about that event.
>
> Beyond this I think if we begin to discuss devices with full colour
> screens that may require richer image/description etc. we should
> really revisit the concept of a "feed".
I guess in a RESTful sense a (authenticated) GET request to
http://www.capitalfm.com/tags/andybee/ should return a list of Tags.
Could that serve as a "feed"?
> I do think it might be worth using the return body to provide a user
> surfacable text response to provide information on the specific of the
> broadcasters implementation.
I'm not familiar with the DAB EPG spec, but one thing we discussed was
whether we leverage that here? So that a GET request for the Tag
resource would return XML in a DAB EPG-compatible format? That would
have two benefits:
i) We wouldn't have to define the format of the response here
ii) The DAB EPG parser could be reused for RadioEPG/DAB EPG support on
the device.
Cheers,
Chris
Andy Buckingham (RadioDNS)
> I guess in a RESTful sense a (authenticated) GET request to
> http://www.capitalfm.com/tags/andybee/ should return a list of Tags. Could
> that serve as a "feed"?
Possibly, although currently that URL is ambiguous. How would the
device obtain this URL?
I was thinking more along the lines of what was previously proposed, a
really simple document served from a fixed URL on the same resolved
tag server. An array of Headline, Link, Image URL, description. If you
have a token, this is used. If not a device can attempt to call it
with just a device ID, it's up to the service provider whether they
403 and require auth or not. For example:
GET /feed
Authorization: OAuth ABCD1234TOKEN1234
..
HTTP/1.1 200 OK
[{"headline": "Adele - Rolling in the Deep played by The Bassman on Capital",
"image": "http://www.capitalfm.com/img/adele.jpg",
"link": "http://www.capitalfm.com/tags/andybee/1234",
"description": "You tagged Adele's new track on The Bassman's show
on Capital. Check the website for details on how you could see her at
a special intimate gig."}]
The benefit of using the fixed URL is also that a device can, in
theory, call this without ever having tagged (or even if a tag failed
auth). This way a service provider might surface a dummy "demo tag"
which links to a tutorial about how tagging works or explains this
particular broadcaster requires registration and talk them through
this process, explaining the reason for the initial tag refusal.
> I'm not familiar with the DAB EPG spec, but one thing we discussed was
> whether we leverage that here? So that a GET request for the Tag resource
> would return XML in a DAB EPG-compatible format? That would have two
> benefits:
>
> i) We wouldn't have to define the format of the response here
> ii) The DAB EPG parser could be reused for RadioEPG/DAB EPG support on the
> device.
I'm not sure the DAB EPG spec would lend much relevance in this
particular use case. I was suggesting a really simple string for
display on the device. In theory, the body could *just* be the string.
The only reason to suggest wrapping it in JSON was on the basis that
the OAuth calls typically use a JSON body for token exchange etc. Just
a suggestion for consistency, the real point of this response was to
keep it very simple.