RadioTAG Specification Version 1.00 (draft 1)

Contents

1 Abstract

This document specifies version 1.00 of the RadioTAG protocol.

The RadioTAG protocol defines how a client (e.g. an IP-enabled radio) discovers whether a broadcaster supports RadioTAG and if so how it then communicates with a broadcaster-provided web service to record the time and station being listened to.

The protocol defines how a client obtains authorization to store data on the server and how it can become paired with a user account so that data can be accessed via the web.

The protocol also defines the format and content of the requests and responses that pass between the client and server.

2 How to read this document

The document starts with an overview of the concepts underlying the RadioTAG protocol. These concepts are summarized in the glossary.

To get an idea of how the RadioTAG protocol works in practice, read the two narratives. These step through the two most common scenarios to show what is communicated between the client (radio) and the tag service at the HTTP level. This section is particularly useful for developers who want to understand how the various bits of the API hang together.

For full details about each endpoint provided by the tag service, read the API section.

Finally, to see how the Atom format is used in tag responses, what each element contains and what limits apply, see data formats.

3 Concepts

A client sends a tag request to a tag service, specifying a time and station. The tag service responds by sending a tag entry containing relevant metadata. The tag data may be stored on the server and may be viewed on the client or on the web or be used for another application.

3.1 Service discovery

[TODO] RadioDNS lookup.

3.2 HTTPS

[TODO] All API calls must use HTTPS.

3.3 Tag requests

A tag request specifies a time and station. The time is specified using seconds since Jan 1 1970, i.e. the Unix epoch. The station is specified using the RadioDNS broadcast parameters.

How that information is interpreted is up to the broadcaster.

3.4 Tag responses

The content of the response to a tag request is up to the broadcaster but must follow the Atom Syndication Format as specified below. A tag response could contain programme, now playing metadata, an advertising message or the response to a call for action.

3.5 Clients, radios and devices

In this specification, the client is any device or software program that implements the client side of the RadioTAG specification. While this would most commonly be an IP-enabled radio, it could also be, say, an application running on a mobile phone or in a web browser.

3.6 The tag service

The tag service is the web service provided by the broadcaster to respond to client requests. It must implement a number of endpoints depending on the level of service it provides.

3.7 Levels of service

There are three levels of service a tag service can provide:

  • anonymous tagging
  • unpaired tagging
  • paired tagging

Pairing in this context means associating your radio with an authenticated user account.

The levels of service are distinguished by whether or not tags are retrievable on the device or on the web and by whether you need an account on the broadcaster's web service. The table below summarizes the differences:

Level of serviceTag list on deviceTag list on webAccount needed
AnonymousNoNoNo
UnpairedYesNoNo
PairedYesYesYes

These services can be offered in a number of combinations. For example, a service may offer anonymous tagging by default which can be upgraded to paired tagging or it may support tagging out of the box (unpaired) with no option to pair the device to a web account. These are the possible combinations:

  • Anonymous only
  • Anonymous upgradeable to paired
  • Unpaired only
  • Unpaired upgradeable to paired
  • Paired only

3.8 Anonymous tagging

Anonymous tagging is the minimal level of service. The broadcaster must provide the following endpoint:

A POST to this endpoint should return metadata relevant to the station and time specified in the request. Tags are not stored on the server so it is not possible to retrieve a list of tags on the client.

3.9 Unpaired tagging

Unpaired tagging is designed to provide an "out-of-the-box" experience without the user having to create an account and pair the client. The protocol enables the client to become authorized to store tags on the server without being associated with an authenticated user account.

To indicate that it supports unpaired tagging, the server must issue an unpaired grant in response to an unauthorized request to POST /tag. It must provide the following endpoints:

Tags are stored on the server. The server must be able to store at least 10 tags per client. There is no upper limit. A typical implementation would store the tags as a FIFO list. When the list is full, a new tag would replace the oldest in the list.

A client should implement an interface to display the current list of tags associated with it as returned by the GET /tags method.

3.10 Paired tagging

Paired tagging is where the client has been paired to a user's account on a tag service. The same limits apply as for unpaired tagging, though a typical implementation will not put any limit on how many tags a user can create.

A tag service that allows paired tagging must provide the following endpoints:

3.11 Authorization

Authorization is based on OAuth 2.0. The central concepts here are tokens and grants.

To store or retrieve anything at the tag service, a client needs a token. A valid token authorizes the client to perform a specific set of actions. In the case of RadioTAG, those actions are to create a tag or get a list of tags for either an unpaired or paired account.

To obtain a token, the client must use the grant passed back from the server in a response header.

A token is like a key. If you have it in your hand, you can open the door. A grant is like a chit giving you permission to request a key. In the RadioTAG protocol, you can't do anything with a grant except attempt to obtain the corresponding token.

4 Glossary

TermDefinition
UnpairedWhere a device has not been associated with a user account
PairedWhere a device has been associated with a user account
GrantTemporary permission to request a service
ScopeWhat a grant applies to
Auth TokenAn authorization token which permits you to create a tag
Unix TimeThe number of seconds elapsed since midnight Coordinated Universal Time (UTC) on January 1, 1970, not counting leap seconds

5 Narratives

5.1 Unpaired to paired

This section describes the requests and responses made between a client and a RadioTAG server when the server supports both unpaired and paired tagging.

5.1.1 Tune radio to BBC Radio 4

After tuning to BBC Radio 4, a RadioDNS look-up is performed to resolve the broadcast parameters into a hostname for the RadioTAG service.

Having ascertained that the service supports RadioTAG, the client makes available a Tag button.

5.1.2 Press tag

The user presses the Tag button.

5.1.2.1 Request

The client makes a POST request to the tag service with the station identifier (using the broadcast parameter string used in constructing a RadioDNS FQDN), and a time. Unix Time is used for the time parameter.

As this client has no Auth Token, the X-Radiotag-Auth-Token header is blank. It could also simply not be there at all. The following sequence of events is also triggered when the request contains an invalid authentication token.

POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312800146
5.1.2.2 Response

To mitigate the possibility of resource depletion attacks, when the server supports unpaired tagging we introduce a two-step process to obtain a token before being allowed to tag. The first step involves obtaining a grant. A grant is temporary permission to make a specific request.

When a tag service supports unpaired tagging, it responds to an unauthenticated /tag request by returning a 401 Unauthorized response containing a grant that allows the device to request an authentication token. This grant consists of two parts: a scope which indicates that the server supports unpaired tagging, and a token which is used in the subsequent request to /token.

A general principle is that a grant is only guaranteed to be valid on the next request, so should not be stored permanently.

HTTP/1.1 401 Unauthorized↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 401 Unauthorized↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: unpaired↵
X-RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 18↵
↵
Must request token
5.1.2.3 Request

The client POSTs the grant to the /token endpoint to request a token to create tags.

POST /token HTTP/1.1↵
Content-Length: 69↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
grant_scope=unpaired&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188
5.1.2.4 Response

The authentication token is returned to the client in the headers of a 204 No Content response.

HTTP/1.1 204 No Content↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 204 No Content↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: a0654d97-22b3-460b-8d77-49b80fd9f93d↵
↵
5.1.2.5 Request

Now the client has successfully exchanged a grant for a token, the tag request can be made again, this time passing the authentication token in a header of a POST request to /tag.

POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: a0654d97-22b3-460b-8d77-49b80fd9f93d↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312800146
5.1.2.6 Response

The server verifies the request by checking the token against those that it has issued, and if valid creates a tag. The metadata corresponding to this tag is returned in the body of a 201 Created response, in the form of an Atom document. See Data formats for more details.

An example entry for a tag created during an episode of a BBC Radio 4 programme is shown below:

HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:42:26Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:e7005bbf-d006-4286-a30d-da7a59c97408</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=746"/>
    <id>urn:uuid:e7005bbf-d006-4286-a30d-da7a59c97408</id>
    <updated>2011-08-08T10:42:26Z</updated>
    <published>2011-08-08T10:42:26Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.1.3 Press OK

In the previous, successful /tag request, the server's response contained a can_register grant. The presence of this grant indicates to the client that the server supports the pairing a client with a user account. At this stage the client can present to the user the option to register with the server, or to accept the information in the current tag and return to the default state for the station.

In this case, we chose the latter by pressing OK.

5.1.4 Press Tags

As the server supports unpaired tagging the tags created so far have been stored on the server against the authentication token, which stands in for a client id. The client can request a list of tags by making a GET request to /tags with the authentication token in the header:

5.1.4.1 Request
GET /tags HTTP/1.1↵
X-Radiotag-Auth-Token: a0654d97-22b3-460b-8d77-49b80fd9f93d↵
Host: radiotag.bbc.co.uk↵
↵
5.1.4.2 Response

The server responds with an Atom feed containing a list of tags created for this device.

HTTP/1.1 200 OK↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Tag List</title>
  <link href="http://radiotag.bbc.co.uk/tags"/>
  <link href="http://radiotag.bbc.co.uk/tags" rel="self"/>
  <updated>2011-08-08T10:42:26Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:07bb8a81-540c-4526-93b2-3a29e92ba45f</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=746"/>
    <id>urn:uuid:e7005bbf-d006-4286-a30d-da7a59c97408</id>
    <updated>2011-08-08T10:42:26Z</updated>
    <published>2011-08-08T10:42:26Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.1.5 Press Tag

We now show the flow of interactions when a user decides to register their client with the service. The process begins with the user pressing the Tag button as before.

5.1.5.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: a0654d97-22b3-460b-8d77-49b80fd9f93d↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312800146
5.1.5.2 Response

The response in this case is a 201 Created, since the service supports unpaired tagging and the client has passed in the authentication token with the request to /tag. Again the response contains a can_register grant. The client uses the presence of this grant to decide to display the option to register.

HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:42:26Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:bd851e72-aff7-4cb9-89fe-cf838143b5ec</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=746"/>
    <id>urn:uuid:bd851e72-aff7-4cb9-89fe-cf838143b5ec</id>
    <updated>2011-08-08T10:42:26Z</updated>
    <published>2011-08-08T10:42:26Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.1.6 Press Register

This time the user selects the option to register on the client. The client requires an identifier to identify itself to the server during the registration process. It requests this from the tag service by making a POST request to the /registration_key endpoint, sending back the grant_scope and grant_token from the previous response.

5.1.6.1 Request
POST /registration_key HTTP/1.1↵
Content-Length: 73↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
grant_scope=can_register&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a
5.1.6.2 Response

The service responds with a registration key in the header, and the location of a web site where the user can complete the registration process.

HTTP/1.1 204 No Content↵
Date: Mon, 08 Aug 2011 10:42:26 GMT↵
Status: 204 No Content↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Registration-Key: 1eb0db2d↵
X-RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵
↵

5.1.7 Register with a web front end

Registering with a web front end and obtaining the authenticating PIN number is outside the scope of RadioTAG, so is not specified here.

The following is a sketch of how this part of the system might be implemented:

The desired outcome of registering is that the registration key is associated with a user's account and a PIN returned to the user. The combination of registration key (which is already known to the client) and the PIN will be used to request an authenticated token in the /register step below. The tag service needs then to be able to map that token to the corresponding user account.

A typical scenario would be that the user visits the broadcaster's web front end, authenticates by some means with the provider of the tagging service (using their user name and password, for example), and submits the registration key obtained in the previous step using a form.

This causes a request to be made to the service which has previously stored the registration key that was issued to the client in the previous step. The service then checks the authenticity and, if valid, issues a PIN number, which is then displayed to the user.

At the backend, the registration key and PIN are stored against the user account so that when the /register request is made, they can be validated and exchanged for a token.

5.1.8 Enter the PIN

The user enters the PIN number obtained in the previous step into their client, which then makes a POST request to /register with the registration key and PIN in the body of the request.

Note that the previously issued authentication token for unpaired tagging is included in the header of the request. This allows the server to migrate tags from an unpaired client to the user's account.

5.1.8.1 Request
POST /register HTTP/1.1↵
X-Radiotag-Auth-Token: a0654d97-22b3-460b-8d77-49b80fd9f93d↵
Content-Length: 34↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
registration_key=1eb0db2d&pin=1879
5.1.8.2 Response

The server checks the credentials and returns 201 Created to indicate that a new token has been created. The response headers contain the new authentication token (X-RadioTAG-Auth-Token), which is to be used for future tagging requests that wish to be associated with this user account. Also in the headers is the user account name (X-RadioTAG-Account-Name). This account name can be used by the client to provide a reminder or prompt to the user in case they are unsure of the account they used to register the client.

HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:42:27 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: f0a85088-98b2-48ce-92b6-43c0d90e60d6↵
X-RadioTAG-Account-Name: sean↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 0↵
↵

5.1.9 Press Tag

The client now has a token which identifies the client with the user account on the server. Subsequent tag requests are made as POSTs to /tag with this token sent in the request headers, so that they can be stored against the user's account.

5.1.9.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: f0a85088-98b2-48ce-92b6-43c0d90e60d6↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312800147
5.1.9.2 Response
HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:42:27 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: f0a85088-98b2-48ce-92b6-43c0d90e60d6↵
X-RadioTAG-Account-Name: sean↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:42:27Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:bd04298d-9ec1-4e62-9b5b-90f376fe3340</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=747"/>
    <id>urn:uuid:bd04298d-9ec1-4e62-9b5b-90f376fe3340</id>
    <updated>2011-08-08T10:42:27Z</updated>
    <published>2011-08-08T10:42:27Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.1.10 Press Tags

The client can again request a list of tags, this time using the new authentication token. The server has migrated the tags created while the client was unpaired to the user's account, so all three tags created above are returned in the Atom feed.

5.1.10.1 Request
GET /tags HTTP/1.1↵
X-Radiotag-Auth-Token: f0a85088-98b2-48ce-92b6-43c0d90e60d6↵
Host: radiotag.bbc.co.uk↵
↵
5.1.10.2 Response
HTTP/1.1 200 OK↵
Date: Mon, 08 Aug 2011 10:42:27 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: f0a85088-98b2-48ce-92b6-43c0d90e60d6↵
X-RadioTAG-Account-Name: sean↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 2138↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Tag List</title>
  <link href="http://radiotag.bbc.co.uk/tags"/>
  <link href="http://radiotag.bbc.co.uk/tags" rel="self"/>
  <updated>2011-08-08T10:42:27Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:892699a9-d9f5-42c9-bd63-96f32d445d20</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=747"/>
    <id>urn:uuid:bd04298d-9ec1-4e62-9b5b-90f376fe3340</id>
    <updated>2011-08-08T10:42:27Z</updated>
    <published>2011-08-08T10:42:27Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=746"/>
    <id>urn:uuid:e7005bbf-d006-4286-a30d-da7a59c97408</id>
    <updated>2011-08-08T10:42:26Z</updated>
    <published>2011-08-08T10:42:26Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=746"/>
    <id>urn:uuid:bd851e72-aff7-4cb9-89fe-cf838143b5ec</id>
    <updated>2011-08-08T10:42:26Z</updated>
    <published>2011-08-08T10:42:26Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.2 Anonymous to paired

This section shows the HTTP traces of transactions between a RadioTag client (e.g. a radio) and a RadioTag service. It covers the scenario where the RadioTag service permits anonymous tagging upgradeable to paired tagging, i.e. it provides a response to an unauthorized client but does not store tags until the client has been paired with a user account.

Here we deal only with the differences between this scenario and the unpaired-to-paired scenario above. Please refer to that document for more information.

5.2.1 Press Tag

The user presses the Tag button. Note that the request is exactly the same as in the unpaired case above.

5.2.1.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312799795
5.2.1.2 Response

The response is a 200 OK rather than a 201 Created. The client should remember this result for later as it indicates that the client should resubmit the tag request after registration.

Note that just like the unpaired case, the response contains a can_register grant. The client can use this to provide the choice to accept the result or to register the client.

HTTP/1.1 200 OK↵
Date: Mon, 08 Aug 2011 10:36:35 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:36:35Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:46cfdeca-4eb7-4465-86df-1cc69fbcec06</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=395"/>
    <id>urn:uuid:46cfdeca-4eb7-4465-86df-1cc69fbcec06</id>
    <updated>2011-08-08T10:36:35Z</updated>
    <published>2011-08-08T10:36:35Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.2.2 Press OK

At this point, the client can forget the stored 200 OK result code.

5.2.3 Press Tags

5.2.3.1 Request
GET /tags HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Host: radiotag.bbc.co.uk↵
↵
5.2.3.2 Response

As this service does not provide unpaired tagging, there are no tags stored on the server.

HTTP/1.1 401 Unauthorized↵
Date: Mon, 08 Aug 2011 10:36:35 GMT↵
Status: 401 Unauthorized↵
X-RadioTAG-Service-Provider: BBC↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 12↵
↵
Unauthorized

5.2.4 Press Tag

5.2.4.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312799795
5.2.4.2 Response

Again, the client should remember that the return code for this /tag request is 200.

HTTP/1.1 200 OK↵
Date: Mon, 08 Aug 2011 10:36:35 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:36:35Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:f4f1a829-a193-4830-937a-5f0f68c56537</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=395"/>
    <id>urn:uuid:f4f1a829-a193-4830-937a-5f0f68c56537</id>
    <updated>2011-08-08T10:36:35Z</updated>
    <published>2011-08-08T10:36:35Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

5.2.5 Press Register

5.2.5.1 Request
POST /registration_key HTTP/1.1↵
Content-Length: 73↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
grant_scope=can_register&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a
5.2.5.2 Response
HTTP/1.1 204 No Content↵
Date: Mon, 08 Aug 2011 10:36:35 GMT↵
Status: 204 No Content↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Registration-Key: 0eff270a↵
X-RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵
↵

5.2.6 Register with the web front end to get a PIN

Registering with a web front end is outside the scope of the RadioTAG specification. See the section above for one possible implementation.

5.2.7 Enter PIN

5.2.7.1 Request

Note that unlike the unpaired case, there is no auth token to send.

POST /register HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 34↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
registration_key=0eff270a&pin=5795
5.2.7.2 Response

The client has now completed the pairing process so receives an X-RadioTAG-Auth-Token header which it should include as a request header in all future requests.

HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:36:36 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: 9357f8f5-d005-46ca-94ae-13da76a1a8ac↵
X-RadioTAG-Account-Name: sean↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 0↵
↵
5.2.7.3 Request

The client should have stored the result of the previous request to /tag. As it was a 200 OK rather than 201 Created, the client knows it should resubmit the tag request, this time including the newly acquired X-RadioTAG-Auth-Token in the request header:

POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: 9357f8f5-d005-46ca-94ae-13da76a1a8ac↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312799796
5.2.7.4 Response

This time the response status is 201 Created to indicate that the tag data has been stored on the server and can be retrieved both on the device and via the web.

HTTP/1.1 201 Created↵
Date: Mon, 08 Aug 2011 10:36:36 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: 9357f8f5-d005-46ca-94ae-13da76a1a8ac↵
X-RadioTAG-Account-Name: sean↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 986↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.bbc.co.uk"/>
  <link href="http://radiotag.bbc.co.uk" rel="self"/>
  <updated>2011-08-08T10:36:36Z</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:5d8a21fd-76fe-4f59-9ff5-717f5a9f0eaf</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://radiotag.bbc.co.uk/images/episode/b0125g85_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b0125g85?t=396"/>
    <id>urn:uuid:5d8a21fd-76fe-4f59-9ff5-717f5a9f0eaf</id>
    <updated>2011-08-08T10:36:36Z</updated>
    <published>2011-08-08T10:36:36Z</published>
    <summary>'Nuit of the Living Dead' and 'The End of the Affair'.</summary>
  </entry>
</feed>

6 API

6.1 POST /tag

6.1.1 Request

6.1.1.1 Headers
NameValue
X-RadioTAG-Auth-TokenEmpty OR unpaired token OR paired token
6.1.1.2 Parameters
NameValue
stationRadioDNS broadcast parameters joined with dots, e.g. "0.c224.ce15.ce1.dab"
timeWhole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch)

6.1.2 Response

6.1.2.1 Status
HTTP Status CodeHTTP StatusExplanation
200OKThe service does not store tags but has returned metadata in Atom format
201CreatedThe service has stored the requested tag
401UnauthorizedThe token is blank or does not match either an unpaired or paired account
6.1.2.2 Headers
NameValue
X-RadioTAG-Service-ProviderThe display name of the tag service provider
X-RadioTAG-Grant-Scope"unpaired" or "can_register". See Grants.
X-RadioTag-Grant-TokenThe token to use when exercising the grant.

If a grant header is not returned, then the server supports only anonymous tags.

6.1.2.3 Body

On a successful request (status 200 or 201), the body contains an Atom feed containing a single entry representing the tag. See Data formats below.

On an unsuccessful request, the body may be blank or may contain a short explanation of why the request failed.

6.1.3 Example 1 - POST /tag with no token

6.1.3.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312301004
6.1.3.2 Response
HTTP/1.1 401 Unauthorized↵
Date: Tue, 02 Aug 2011 16:03:24 GMT↵
Status: 401 Unauthorized↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: unpaired↵
X-RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 18↵
↵
Must request token

6.1.4 Example 2 - POST /tag with a valid unpaired token

6.1.4.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: be222d22-4cef-439e-a77c-c867441dcb33↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312301004
6.1.4.2 Response
HTTP/1.1 201 Created↵
Date: Tue, 02 Aug 2011 16:03:25 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 957↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>PM</title>
  <link href="http://radiotag.example.com"/>
  <link href="http://radiotag.example.com" rel="self"/>
  <updated>2011-08-02T17:03:24+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:fb669d2c-63b3-420b-9dd6-131f5d58e68a</id>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=204"/>
    <id>urn:uuid:fb669d2c-63b3-420b-9dd6-131f5d58e68a</id>
    <updated>2011-08-02T17:03:24+01:00</updated>
    <published>2011-08-02T17:03:24+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
</feed>

Note that the response header contains the X-RadioTAG-Grant-Scope can_register. This will be present only if the service supports paired tagging.

6.1.5 Example 3 - POST /tag with a valid paired token

6.1.5.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312302129
6.1.5.2 Response
HTTP/1.1 201 Created↵
Date: Tue, 02 Aug 2011 16:22:09 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵
X-RadioTAG-Account-Name: sean↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 958↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>PM</title>
  <link href="http://radiotag.example.com"/>
  <link href="http://radiotag.example.com" rel="self"/>
  <updated>2011-08-02T17:22:09+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97</id>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=1329"/>
    <id>urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97</id>
    <updated>2011-08-02T17:22:09+01:00</updated>
    <published>2011-08-02T17:22:09+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
</feed>

Note that the response header does not contain any grants but does contain the paired account name.

6.1.6 Example 4 - POST /tag against a service that does not provide unpaired tagging

6.1.6.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312195118
6.1.6.2 Response
HTTP/1.1 200 OK↵
Date: Mon, 01 Aug 2011 10:38:38 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 992↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.example.com"/>
  <link href="http://radiotag.example.com" rel="self"/>
  <updated>2011-08-01T11:38:38+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b01211y4_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b01211y4?t=518"/>
    <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
    <updated>2011-08-01T11:38:38+01:00</updated>
    <published>2011-08-01T11:38:38+01:00</published>
    <summary>'Me Talk Pretty One Day' and 'It's Catching'.</summary>
  </entry>
</feed>

6.1.7 Example 5 - POST /tag against a service that provides only anonymous tagging

6.1.7.1 Request
POST /tag HTTP/1.1↵
X-Radiotag-Auth-Token: ↵
Content-Length: 43↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
station=0.c224.ce15.ce1.dab&time=1312195118
6.1.7.2 Response
HTTP/1.1 200 OK↵
Date: Mon, 01 Aug 2011 10:38:38 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 992↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.example.com"/>
  <link href="http://radiotag.example.com" rel="self"/>
  <updated>2011-08-01T11:38:38+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b01211y4_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b01211y4?t=518"/>
    <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
    <updated>2011-08-01T11:38:38+01:00</updated>
    <published>2011-08-01T11:38:38+01:00</published>
    <summary>'Me Talk Pretty One Day' and 'It's Catching'.</summary>
  </entry>
</feed>

Note that no grant headers are issued.

6.2 POST /token

6.2.1 Request

6.2.1.1 Headers

None.

6.2.1.2 Parameters
NameValue
grant_scopeThe value of the X-RadioTAG-Grant-Scope provided in the previous request
grant_tokenThe value of the X-RadioTAG-Grant-Token provided in the previous request

For more information, see Grants.

6.2.1.3 Example
POST /token HTTP/1.1↵
Content-Length: 69↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
grant_scope=unpaired&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188

6.2.2 Response

6.2.2.1 Status
HTTP Status CodeHTTP StatusExplanation
6.2.2.2 Headers
NameValue
X-RadioTAG-Service-ProviderThe display name of the tag service provider
X-RadioTag-Auth-TokenThe token to use when exercising the grant.
6.2.2.3 Body

The /token endpoint should not return any content (as denoted by the 204 status code).

6.2.2.4 Example
HTTP/1.1 204 No Content↵
Date: Tue, 02 Aug 2011 16:22:08 GMT↵
Status: 204 No Content↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵
↵

6.3 GET /tags

6.3.1 Request

6.3.1.1 Headers
NameValue
X-RadioTAG-Auth-TokenUnpaired token OR paired token
6.3.1.2 Parameters

None.

6.3.1.3 Example
GET /tags HTTP/1.1↵
X-Radiotag-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵
Host: radiotag.bbc.co.uk↵
↵

6.3.2 Response

6.3.2.1 Status
HTTP Status CodeHTTP StatusExplanation
200OKThe request was successful
401UnauthorizedThe token is invalid or the service does not allow storing of tags
6.3.2.2 Headers
NameValue
X-RadioTAG-Service-ProviderThe display name of the tag service provider
X-RadioTAG-Grant-ScopeIf the service provides pairing, this will have the value can_register. See Grants
X-RadioTag-Grant-TokenThe token to use when exercising the can_register grant
6.3.2.3 Body
6.3.2.4 Example
HTTP/1.1 200 OK↵
Date: Tue, 02 Aug 2011 16:22:08 GMT↵
Status: 200 OK↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Grant-Scope: can_register↵
X-RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵
Content-Type: application/xml;charset=utf-8↵
Content-Length: 974↵
↵
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Tag List</title>
  <link href="http://radiotag.example.com/tags"/>
  <link href="http://radiotag.example.com/tags" rel="self"/>
  <updated>2011-08-02T17:22:08+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:6a041e97-65bb-4b12-82da-c1b373731905</id>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=1328"/>
    <id>urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d</id>
    <updated>2011-08-02T17:22:08+01:00</updated>
    <published>2011-08-02T17:22:08+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
</feed>

6.4 POST /registration_key

6.4.1 Request

6.4.1.1 Headers
NameValue
X-RadioTAG-Auth-TokenEither blank or a valid unpaired token
6.4.1.2 Parameters
NameValue
grant_scopeMust be the value can_register
grant_tokenMust be the grant token issued in the previous request
6.4.1.3 Example
POST /registration_key HTTP/1.1↵
Content-Length: 73↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
grant_scope=can_register&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a

6.4.2 Response

6.4.2.1 Status
HTTP Status CodeHTTP StatusExplanation
204No ContentThe request was successful. The response headers contain the registration key required to pair the radio.
6.4.2.2 Headers
NameValue
X-RadioTAG-Service-ProviderThe display name of the tag service provider
X-RadioTag-Registration-KeyThe registration key to use when pairing the device.
X-RadioTag-Registration-UrlThe url to visit to register the device.
6.4.2.3 Body

This response contains no body.

6.4.2.4 Example
HTTP/1.1 204 No Content↵
Date: Tue, 02 Aug 2011 16:22:09 GMT↵
Status: 204 No Content↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Registration-Key: 2b188492↵
X-RadioTAG-Registration-Url: http://radiotag.example.com/↵
↵

6.5 POST /register

6.5.1 Request

6.5.1.1 Headers
NameValue
X-RadioTAG-Auth-TokenUnpaired token OR paired token
6.5.1.2 Parameters
NameValue
registration_keyThe registration key returned from the /registration_key request
pinThe PIN issued to the user (e.g. at a web front end).
6.5.1.3 Example
POST /register HTTP/1.1↵
X-Radiotag-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵
Content-Length: 34↵
Content-Type: application/x-www-form-urlencoded↵
Host: radiotag.bbc.co.uk↵
↵
registration_key=2b188492&pin=3612

6.5.2 Response

6.5.2.1 Status
HTTP Status CodeHTTP StatusExplanation
201CreatedThe registration has succeeded and the device has been paired to the associated account
6.5.2.2 Headers
NameValue
X-RadioTAG-Service-ProviderThe display name of the tag service provider
X-RadioTag-Auth-TokenThe token to use when exercising the grant.
X-RadioTag-Account-NameThe display name of the associated paired account.
6.5.2.3 Body

There is no body returned in this response.

6.5.2.4 Example
HTTP/1.1 201 Created↵
Date: Tue, 02 Aug 2011 16:22:09 GMT↵
Status: 201 Created↵
X-RadioTAG-Service-Provider: BBC↵
X-RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵
X-RadioTAG-Account-Name: sean↵
Content-Type: text/html;charset=utf-8↵
Content-Length: 0↵
↵

7 Data formats

7.1 Tag data

All server responses containing tags use the Atom Syndication Format to represent tags, with some extensions under a RadioTAG namespace.

In the following, the element prefix "radiotag:" indicates the RadioTag namespace. All other elements are assumed to be from the Atom namespace.

Atom defines these elements as required:

ElementDescriptionMax length
idunique identifier for this tag ref48
titlebroadcaster generated title ref128
updatedthe datetime the tag was modified ref20

All dates are UTC in ISO format (ISO 8601 or RFC3339), e.g. 2011-08-08T09:00:00Z.

The RadioTAG specification also requires the following:

ElementDescriptionMax length
authorname of tag service provider (e.g. BBC, Global)16
publishedthe datetime of creation (= tag time)20
summarytext only - i.e. must not include HTML tags180
link rel="image"link to 100x100 image representing the tag512
link rel="self"a user accessible url for the tag512
radiotag:servicethe human-readable name of the service taggedTBD
radiotag:sidRadioDNS service identifier32

Note the difference here between id and link rel="self". id is a globally unique identifier. link rel="self" gives the url as visible to the device/user (i.e. scoped by the auth token).

Also note that we are interpreting the published entry as equivalent to the tag time. The updated element can be used to indicate that the tag data has been updated, e.g. the description has changed.

The example below shows these elements in context:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Meet David Sedaris</title>
  <link href="http://radiotag.example.com"/>
  <link href="http://radiotag.example.com" rel="self"/>
  <updated>2011-08-01T11:38:38+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
  <entry>
    <title>Meet David Sedaris</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b01211y4_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b01211y4?t=518"/>
    <id>urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249</id>
    <updated>2011-08-01T11:38:38+01:00</updated>
    <published>2011-08-01T11:38:38+01:00</published>
    <summary>'Me Talk Pretty One Day' and 'It's Catching'.</summary>
  </entry>
</feed>

7.2 Tags data

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:radiotag="http://radiodns.org/2011/radiotag">
  <title>Tag List</title>
  <link href="http://radiotag.example.com/tags"/>
  <link href="http://radiotag.example.com/tags" rel="self"/>
  <updated>2011-08-02T17:22:09+01:00</updated>
  <author>
    <name>BBC</name>
  </author>
  <id>urn:uuid:bf3e7d30-ccb8-4b45-b438-c790fb2ec5f7</id>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=1329"/>
    <id>urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97</id>
    <updated>2011-08-02T17:22:09+01:00</updated>
    <published>2011-08-02T17:22:09+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=1328"/>
    <id>urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d</id>
    <updated>2011-08-02T17:22:08+01:00</updated>
    <published>2011-08-02T17:22:08+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
  <entry>
    <title>PM</title>
    <radiotag:sid>0.c224.ce15.ce1.dab</radiotag:sid>
    <radiotag:service>BBC Radio 4</radiotag:service>
    <link rel="image" href="http://node1.bbcimg.co.uk/iplayer/images/episode/b012wjd3_150_84.jpg"/>
    <link rel="canonical" href="http://www.bbc.co.uk/programmes/b012wjd3?t=1328"/>
    <id>urn:uuid:8e67aef6-4e8c-47ac-bc10-f89d4d5bac17</id>
    <updated>2011-08-02T17:22:08+01:00</updated>
    <published>2011-08-02T17:22:08+01:00</published>
    <summary>Eddie Mair presents the day's top stories.</summary>
  </entry>
</feed>

8 Limits

Note: These need to be reviewed.

Data elementMax. size in bytesNotes
token48
url512See RFC1738
SRV64RadioDNS
service id (sid)32RadioDNS
author16Atom entry
id48Atom entry
summary180Atom entry
title128Atom entry (compatible with DAB/RDS Livetext)