From 8f188c797996f1a613d7d59372f6f6d08a1708f3 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 12 Feb 2014 15:34:12 +0000 Subject: [PATCH 01/19] Creating Draft 6 document --- src/radiotag-api-proposal-v1.00d6.md | 2024 ++++++++++++++++++++++++++ 1 file changed, 2024 insertions(+) create mode 100644 src/radiotag-api-proposal-v1.00d6.md diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md new file mode 100644 index 0000000..b26d2ad --- /dev/null +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -0,0 +1,2024 @@ +% RadioTAG 1.00 specification, draft 6 +% Sean O'Halpin (BBC R&D); Chris Lowis (BBC R&D) +% 2014-02- +## Front matter +### Authors + +Sean O'Halpin (BBC R&D), Chris Lowis (BBC R&D) + +### Contributors + +Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) + +### Published + +- Draft 1: 2011-09-01 +- Draft 2: 2011-10-27 +- Draft 3: 2012-02-08 + - Changed /register return code from 201 to 204 +- Draft 4: 2012-06-13 + - Conversion to pandoc markdown format +- Draft 5: 2012-07-30 + - Consistent capitalization of headers + - Moved Narrative section into Appendix + - 'anonymous' changed to 'unidentified' + - 'unpaired' changed to 'receiver (identity)' + - 'paired' changed to 'user (identity)' + - 'client' changed to 'receiver' + - 'can_register' changed to 'identity' +- Draft 6: 2014-02- + +### URL + +Unpublished at time of writing + +## Abstract + +This document specifies version 1.00 of the RadioTAG protocol. + +The RadioTAG protocol defines how a receiver (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 receiver 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 receiver and server. + +## How to read this document + +The document starts with an overview of the [concepts](#concepts) +underlying the RadioTAG protocol. These concepts are summarized in the +[glossary](#glossary). + +To get an idea of how the RadioTAG protocol works in practice, read +the two [narratives](#narratives) in the Appendix. These step through the +two most common scenarios to show what is communicated between the +receiver (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](#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](#data-formats). + +## Concepts + +A receiver 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 receiver or on the web or be used for another application. + +### Service discovery + +[TODO] RadioDNS lookup. + +### HTTPS + +[TODO] All API calls must use HTTPS. + +### 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. + +### Tag responses + +The content of the *response* to a tag request is up to the +broadcaster but must follow the [Atom Syndication +Format](http://tools.ietf.org/html/rfc4287) as [specified +below](#tag-data). A tag response could contain programme, now playing +metadata, an advertising message or the response to a call for action. + +### Receivers, radios and devices + +In this specification, the **receiver** is any device or software program +that implements the receiver 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. + +### The tag service + +The **tag service** is the web service provided by the broadcaster to +respond to receiver requests. It must implement a number of endpoints +depending on the level of service it provides. + +### Levels of identity + +There are three levels of identity a tag service can provide: + +- anonymous +- receiver +- user + +*User* in this context refers to an authenticated user account. + +The levels of identification are distinguished by whether or not tags +are retrievable on the device or on the web and by whether you need a +user account on the broadcaster's web service. The table below +summarizes the differences: + +--------------------------------------------------------------------- +Level of identity Tag list on device Tag list on web Account needed +----------------- ------------------ --------------- -------------- +Unidentified No No No + +Receiver Yes No No + +User Yes Yes Yes + +--------------------------------------------------------------------- + +These levels of identification can be provided in a number of +combinations. For example, a service may offer anonymous tagging by +default which can be upgraded to user tagging or it may support +tagging out of the box (receiver) with no option to pair the device to +an online user account. These are the possible combinations: + +- Unidentified only +- Unidentified upgradeable to user +- Receiver only +- Receiver upgradeable to user + +### No identity + +Unidentified tagging is the minimal level of service. The broadcaster must +provide the following endpoint: + +- [POST /tag](#post-tag) + +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 receiver. + +### Receiver identity + +Receiver identity is designed to provide an "out-of-the-box" +experience without the user having to create an account and pair the +receiver. The protocol enables the receiver to become authorized to +store tags on the server without being associated with an +authenticated user account. + +To indicate that it supports receiver identity, the server must issue +a `receiver` [grant](#authorization) in response to an unauthorized request +to `POST /tag`. It must provide the following endpoints: + +- [POST /tag](#post-tag) +- [POST /token](#post-token) +- [GET /tags](#get-tags) + +Tags are stored on the server. The server must be able to store at least +10 tags per receiver. 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 receiver should implement an interface to display the current list of +tags associated with it as returned by the `GET /tags` method. + +Note that with receiver identification, the receiver stores +a token which uniquely identifies it to the tag service for the +lifetime of that token only. If that identity is reset by the receiver +deleting the token, any tags which have been submitted against it are +effectively orphaned. + +### User identity + +User identity is where the receiver has been paired to an +authenticated user's account on a tag service. The same limits apply +as for receiver identification, though a typical implementation will +not put any limit on how many tags a user can create. + +A tag service that enables tagging with a user identity must provide +the following endpoints: + +- [POST /tag](#post-tag) +- [POST /token](#post-token) +- [GET /tags](#get-tags) +- [POST /registration\_key](#post-registration_key) +- [POST /register](#post-register) + +### 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 receiver needs a +**token**. A valid token authorizes the receiver to perform a specific +set of actions. In the case of RadioTAG, those actions are to [create +a tag](#post-tag) or [get a list of tags](#get-tags) for either a +[receiver](#receiver-identity) identity or [user](#user-identity) +account identity. + +To obtain a token, the receiver 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. + +## Glossary + +--------------------------------------------------------------------------------------- +Term Definition +--------------- -------------------------------------------------------------------- +Receiver The device or user agent which interacts with the RadioTAG service + +Receiver identity A RadioTAG identity associated only with a specific receiver and + *not* with a user account + +User identity A RadioTAG identity where a receiver has been associated with a user + account, and which can then be accessed from any receiver which has + been similarly associated + +Grant Temporary permission to request a service + +Scope What a grant applies to + +Auth Token An authorization token which permits you to create a tag + +Unix Time The number of seconds elapsed since midnight Coordinated Universal + Time (UTC) on January 1, 1970, not counting leap seconds + +-------------------------------------------------------------------------------------- + +## API + +### Some general points + +Requests pass information in a combination of HTTP headers and form +encoded POST parameters. + +Responses pass data back in a combination of HTTP headers and XML. + +While headers are shown here in a canonical form, due to the fact that +proxies and other intermediaries may adjust HTTP headers, both receiver +and server implementations should be prepared to accept header *keys* +in any mixture of upper and lower case. One common way to handle this +is to downcase all header keys on reading. Header *values* on the +other hand should not be changed by intermediaries and should be read +as is. + +UTF-8 is the only supported character set. + +### Common response headers + +-------------------------------------------------------------------------------- +Name Value +--------------------------- --------------------------------------------------- +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Account-Name The display name of the associated user account + +RadioTAG-Auth-Token The authorization token for a receiver or user + identity + +-------------------------------------------------------------------------------- + +The `RadioTAG-Service-Provider` header should be returned in all +responses. + +The `RadioTAG-Account-Name` should be returned in all responses to +requests made by a receiver that is paired with a user account. + +The `RadioTAG-Auth-Token` header is returned when the receiver has been +granted authorization. It also enables the tag service to issue a new +token to replace an old one - see the next section. + +### Updating tokens + +The tag service can change the `RadioTAG-Auth-Token` in response to +any authorized request (i.e. one which contains a valid Auth Token). The +receiver should *always* use the last received Auth Token and update any +stored value from that. This provides a way for a tag service to expire +tokens. + +We recommend that tag service implementations allow a period of grace in +which an expired token can co-exist with its replacement. This will +address the case where the token was updated but the response was not +received by the receiver. + +### POST /tag + +#### Request + +##### Headers + +-------------------------------------------------------------- +Name Value +--------------------- --------------------------------------- +RadioTAG-Auth-Token Empty OR receiver token OR user token + +-------------------------------------------------------------- + +##### Parameters + +-------------------------------------------------------------------------------- +Name Value +------- ----------------------------------------------------------------------- +station RadioDNS broadcast parameters joined with dots, e.g. + "0.c224.ce15.ce1.dab" + +time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) + +-------------------------------------------------------------------------------- + +#### Response + +##### Status + +-------------------------------------------------------------------------------- +HTTP Status Code HTTP Status Explanation +---------------- ------------ ------------------------------------------------ +200 OK The service does not store tags but has returned + metadata in Atom format + +201 Created The service has stored the requested tag + +401 Unauthorized Unidentified tagging is not supported and the token + is blank or does not match either a receiver or + user identity + +-------------------------------------------------------------------------------- + +##### Headers + +------------------------------------------------------------------------------- +Name Value +--------------------------- -------------------------------------------------- +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Auth-Token The token to use from now on. + +RadioTAG-Account-Name The display name of the associated user account. + +RadioTAG-Grant-Scope "receiver" or "identity". See [Authorization](#authorization). + +RadioTAG-Grant-Token The token to use when exercising the grant. + +------------------------------------------------------------------------------- + +A grant header is *not* returned in the following cases: + +- the server supports only unidentified tagging +- the receiver is already using a user identity token +- the receiver is using a receiver identity token and the tag service doesn't + support user accounts + +##### 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](#data-formats) below. + +On an unsuccessful request, the body may be blank or may contain a short +explanation of why the request failed. + +#### Example 1 - `POST /tag` with no token + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 401 Unauthorized↵ +Date: Tue, 02 Aug 2011 16:03:24 GMT↵ +Status: 401 Unauthorized↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: receiver↵ +RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ +Content-Type: text/html;charset=utf-8↵ +Content-Length: 18↵ +↵ +Must request token +~~~~ + +#### Example 2 - `POST /tag` with a valid receiver token + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Tue, 02 Aug 2011 16:03:25 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 957↵ +↵ + + + PM + + + 2011-08-02T17:03:24+01:00 + + BBC + + urn:uuid:fb669d2c-63b3-420b-9dd6-131f5d58e68a + 1 + 1 + 1 + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:fb669d2c-63b3-420b-9dd6-131f5d58e68a + 2011-08-02T17:03:24+01:00 + 2011-08-02T17:03:24+01:00 + Eddie Mair presents the day's top stories. + + +~~~~ + +Note that the response header contains the `RadioTAG-Grant-Scope` +`identity`. This will be present only if the service supports user +tagging. + +#### Example 3 - `POST /tag` with a valid user token + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Tue, 02 Aug 2011 16:22:09 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵ +RadioTAG-Account-Name: sean↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 958↵ +↵ + + + PM + + + 2011-08-02T17:22:09+01:00 + + BBC + + urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97 + 1 + 1 + 1 + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97 + 2011-08-02T17:22:09+01:00 + 2011-08-02T17:22:09+01:00 + Eddie Mair presents the day's top stories. + + +~~~~ + +Note that the response header does not contain any grants but does +contain the paired user account name. + +#### Example 4 - `POST /tag` against a service that does not provide receiver tagging + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Mon, 01 Aug 2011 10:38:38 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 992↵ +↵ + + + Meet David Sedaris + + + 2011-08-01T11:38:38+01:00 + + BBC + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 1 + 1 + 1 + + Meet David Sedaris + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 2011-08-01T11:38:38+01:00 + 2011-08-01T11:38:38+01:00 + 'Me Talk Pretty One Day' and 'It's Catching'. + + +~~~~ + +#### Example 5 - `POST /tag` against a service that provides only unidentified tagging + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Mon, 01 Aug 2011 10:38:38 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 992↵ +↵ + + + Meet David Sedaris + + + 2011-08-01T11:38:38+01:00 + + BBC + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 1 + 1 + 1 + + Meet David Sedaris + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 2011-08-01T11:38:38+01:00 + 2011-08-01T11:38:38+01:00 + 'Me Talk Pretty One Day' and 'It's Catching'. + + +~~~~ + +Note that no grant headers are issued. + +### POST /token + +#### Request + +##### Headers + +None. + +##### Parameters + +-------------------------------------------------------------------------------- +Name Value +------------ ------------------------------------------------------------------ +grant\_scope The value of the RadioTAG-Grant-Scope provided in the previous + request + +grant\_token The value of the RadioTAG-Grant-Token provided in the previous + request + +-------------------------------------------------------------------------------- + +For more information, see [Authorization](#authorization). + +##### Example + +~~~~ {.example} +POST /token HTTP/1.1↵ +Content-Length: 69↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +grant_scope=receiver&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 +~~~~ + +#### Response + +##### Status + +-------------------------------------------------------------------------------- +HTTP Status Code HTTP Status Explanation +---------------- ------------ ------------------------------------------------ +204 No Content The token was successfully created + +401 Unauthorized The grant is missing or invalid + +403 Forbidden The grant is valid but the receiver is not allowed + to make this request + +-------------------------------------------------------------------------------- + +##### Headers + +------------------------------------------------------------------------------- +Name Value +--------------------------- -------------------------------------------------- +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Auth-Token The newly issued token to use for future requests. + +------------------------------------------------------------------------------- + +##### Body + +The `/token` endpoint should not return any content (as denoted by the +204 status code). + +##### Example + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Tue, 02 Aug 2011 16:22:08 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ +↵ +~~~~ + +### GET /tags + +#### Request + +##### Headers + +----------------------------------------------------- +Name Value +--------------------- ------------------------------ +RadioTAG-Auth-Token receiver token OR user token + +----------------------------------------------------- + +##### Parameters + +---------------------------------------------------------------- +Name Value +----------- -------------------------------------------------- +startIndex (Optional) the 1-based index of the first result + +itemsPerPage (Optional) maximum number of entries to return + +---------------------------------------------------------------- + +If the caller does not specify `startIndex`, it defaults to 1. + +If the caller does not specify `itemsPerPage`, the number of entries +returned is determined by the server. + +The server specifies the total number of entries that can be returned +in the result set using the `totalResults` element (see below). + +Note: the `startIndex`, `itemsPerPage` and `totalResults` parameters +are based on the [OpenSearch +specification](http://www.oclc.org/developer/platform/query-responses). + +##### Example + +~~~~ {.example} +GET /tags HTTP/1.1↵ +RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ +Host: radiotag.bbc.co.uk↵ +↵ +~~~~ + +#### Response + +##### Status + +-------------------------------------------------------------------------------- +HTTP Status Code HTTP Status Explanation +---------------- ------------ ------------------------------------------------ +200 OK The request was successful + +401 Unauthorized The token is invalid or the service does not + allow storing of tags + +-------------------------------------------------------------------------------- + +##### Headers + +-------------------------------------------------------------------------------- +Name Value +--------------------------- --------------------------------------------------- +RadioTAG-Account-Name The display name of the associated user account + (if applicable) + +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Grant-Scope If the service provides pairing to a user + account, this will have the value `identity`. + See [Authorization](#authorization) + +RadioTAG-Grant-Token The token to use when exercising the `identity` + grant + +-------------------------------------------------------------------------------- + +##### Body + +##### Example + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Tue, 02 Aug 2011 16:22:08 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 974↵ +↵ + + + Tag List + + + 2011-08-02T17:22:08+01:00 + + BBC + + urn:uuid:6a041e97-65bb-4b12-82da-c1b373731905 + 1 + 1 + 1 + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d + 2011-08-02T17:22:08+01:00 + 2011-08-02T17:22:08+01:00 + Eddie Mair presents the day's top stories. + + +~~~~ + +### POST /registration\_key + +#### Request + +##### Headers + +------------------------------------------------------------- +Name Value +--------------------- -------------------------------------- +RadioTAG-Auth-Token Either blank or a valid receiver token + +------------------------------------------------------------- + +##### Parameters + +-------------------------------------------------------------------- +Name Value +------------ ------------------------------------------------------ +grant\_scope Must be the value `identity` + +grant\_token Must be the grant token issued in the previous request + +-------------------------------------------------------------------- + +##### Example + +~~~~ {.example} +POST /registration_key HTTP/1.1↵ +Content-Length: 73↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a +~~~~ + +#### Response + +##### Status + +-------------------------------------------------------------------------------- +HTTP Status Code HTTP Status Explanation +---------------- ----------- ------------------------------------------------- +204 No Content The request was successful. The response headers + contain the + registration key required to pair the radio. + +-------------------------------------------------------------------------------- + +##### Headers + +-------------------------------------------------------------------------------- +Name Value +--------------------------- --------------------------------------------------- +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Registration-Key The registration key to use when pairing the + device. + +RadioTAG-Registration-Url The url to visit to register the device. + +-------------------------------------------------------------------------------- + +##### Body + +This response contains no body. + +##### Example + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Tue, 02 Aug 2011 16:22:09 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Registration-Key: 2b188492↵ +RadioTAG-Registration-Url: http://radiotag.example.com/↵ +↵ +~~~~ + +### POST /register + +#### Request + +##### Headers + +----------------------------------------------------- +Name Value +--------------------- ------------------------------ +RadioTAG-Auth-Token Receiver OR user token + +----------------------------------------------------- + +##### Parameters + +-------------------------------------------------------------------------------- +Name Value +----------------- ------------------------------------------------------------- +registration\_key The registration key returned from the `/registration_key` + request + +pin The PIN issued to the user (e.g. at a web front end). + +-------------------------------------------------------------------------------- + +##### Example + +~~~~ {.example} +POST /register HTTP/1.1↵ +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 +~~~~ + +#### Response + +##### Status + +-------------------------------------------------------------------------------- +HTTP Status Code HTTP Status Explanation +---------------- ----------- ------------------------------------------------- +204 No Content The registration has succeeded and the receiver + has been paired to the associated user account + +-------------------------------------------------------------------------------- + +##### Headers + +------------------------------------------------------------------------------ +Name Value +--------------------------- ------------------------------------------------- +RadioTAG-Service-Provider The display name of the tag service provider + +RadioTAG-Auth-Token The token to use for future requests + +RadioTAG-Account-Name The display name of the associated user account + +------------------------------------------------------------------------------ + +##### Body + +There is no body returned in this response. + +##### Example + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Tue, 02 Aug 2011 16:22:09 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵ +RadioTAG-Account-Name: sean↵ +↵ +~~~~ + +## Data formats + +### Tag data + +All server responses containing tags use the [Atom Syndication +Format](http://tools.ietf.org/html/rfc4287) 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: + +----------------------------------------------------------------------------- +Element Description Max length +------- -------------------------------------------------------- ---------- +id unique identifier for this tag 48 + [ref](http://tools.ietf.org/html/rfc4287#section-4.2.6) + +title broadcaster generated title 128 + [ref](http://tools.ietf.org/html/rfc4287#section-4.2.14) + +updated the datetime the tag was modified 20 + [ref](http://tools.ietf.org/html/rfc4287#section-4.2.15) + +----------------------------------------------------------------------------- + +All dates are UTC in ISO format ([ISO +8601](http://en.wikipedia.org/wiki/ISO8601) or [RFC +3339](http://tools.ietf.org/html/rfc3339)), e.g. `2011-08-08T09:00:00Z`. + +The RadioTAG specification also requires the following: + +----------------------------------------------------------------------------- +Element Description Max length +---------------- ----------------------------------------------- ---------- +author name of tag service provider (e.g. BBC, Global) 16 + +published the datetime of creation (= tag time) 20 + +summary text only - i.e. must not include HTML tags 180 + +link rel="image" link to 100x100 image representing the tag 255 + +link rel="self" a user accessible url for the tag 255 + +radiotag:service the human-readable name of the service tagged 16 + +radiotag:sid RadioDNS service identifier 32 + +----------------------------------------------------------------------------- + +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 255 character limit on urls is based on a strict reading of the note +in paragraph 3 of [RFC 2616 Section +3.2.1](http://tools.ietf.org/html/rfc2616#section-3.2.1). + +The `radiotag:service` limit matches the `mediumNameType` in the EPG +specifications (and also the DAB label length). + +The example below shows these elements in context: + +~~~~ {.example} + + + Meet David Sedaris + + + 2011-08-01T11:38:38+01:00 + + BBC + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 1 + 1 + 1 + + Meet David Sedaris + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 + 2011-08-01T11:38:38+01:00 + 2011-08-01T11:38:38+01:00 + 'Me Talk Pretty One Day' and 'It's Catching'. + + +~~~~ + +### Tags data + +~~~~ {.example} + + + Tag List + + + 2011-08-02T17:22:09+01:00 + + BBC + + urn:uuid:bf3e7d30-ccb8-4b45-b438-c790fb2ec5f7 + 3 + 1 + 3 + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97 + 2011-08-02T17:22:09+01:00 + 2011-08-02T17:22:09+01:00 + Eddie Mair presents the day's top stories. + + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d + 2011-08-02T17:22:08+01:00 + 2011-08-02T17:22:08+01:00 + Eddie Mair presents the day's top stories. + + + PM + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:8e67aef6-4e8c-47ac-bc10-f89d4d5bac17 + 2011-08-02T17:22:08+01:00 + 2011-08-02T17:22:08+01:00 + Eddie Mair presents the day's top stories. + + +~~~~ + +## Limits + +### Data elements + +---------------------------------------------------------------------------------------------- +Data element Max. size in bytes Notes +---------------- ------------------ -------------------------------------------------------- +author 16 Atom entry + +id 48 Atom entry + +pin number 10 + +service id (sid) 32 As specified by RadioDNS + +summary 180 Atom entry + +title 128 Atom entry (compatible with DAB/RDS Livetext) + +token 48 + +url 255 See [RFC 2616 Section + 3.2.1](http://tools.ietf.org/html/rfc2616#section-3.2.1) + +---------------------------------------------------------------------------------------------- + +### HTTP Headers + +----------------------------------------------- +Headers Max. size in bytes +--------------------------- ------------------ +RadioTAG-Account-Name 48 + +RadioTAG-Auth-Token 48 + +RadioTAG-Grant-Scope 16 + +RadioTAG-Grant-Token 48 + +RadioTAG-Registration-Key 10 + +RadioTAG-Registration-Url 128 + +RadioTAG-Service-Provider 16 + +----------------------------------------------- + +# Appendix + +## Narratives + +### From receiver to user pairing + +This section describes the requests and responses made between a +receiver and a RadioTAG server when the server supports both receiver +and user tagging. + +#### 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 receiver makes +available a `Tag` button. + +#### Press tag + +The user presses the `Tag` button. + +##### Request + +The receiver 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 receiver has no Auth Token, the `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. + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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=1319201989 +~~~~ + +##### Response + +To mitigate the possibility of resource depletion attacks, when the +server supports receiver 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 receiver 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 receiver 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. + +~~~~ {.example} +HTTP/1.1 401 Unauthorized↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 401 Unauthorized↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: receiver↵ +RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ +Content-Type: text/html;charset=utf-8↵ +Content-Length: 18↵ +↵ +Must request token +~~~~ + +##### Request + +The receiver POSTs the grant to the `/token` endpoint to request a token +to create tags. + +~~~~ {.example} +POST /token HTTP/1.1↵ +Content-Length: 69↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +grant_scope=receiver&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 +~~~~ + +##### Response + +The authentication token is returned to the receiver in the headers of a +`204 No Content` response. + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +↵ +~~~~ + +##### Request + +Now the receiver 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`. + +~~~~ {.example} +POST /tag HTTP/1.1↵ +RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Content-Length: 43↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +station=0.c224.ce15.ce1.dab&time=1319201989 +~~~~ + +##### 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](http://tools.ietf.org/html/rfc4287) document. See +[Data formats](#data-formats) for more details. + +An example entry for a tag created during an episode of a BBC Radio 4 +programme is shown below: + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 1032↵ +↵ + + + Feedback + + + 2011-10-21T13:59:49+01:00 + + BBC + + urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 + 1 + 1 + 1 + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 + 2011-10-21T13:59:49+01:00 + 2011-10-21T13:59:49+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + +~~~~ + +#### Press OK + +In the previous, successful `/tag` request, the server's response +contained a `identity` grant. The presence of this grant indicates +to the receiver that the server supports the pairing a receiver with a user +account. At this stage the receiver 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`. + +#### Press Tags + +As the server supports receiver tagging the tags created so far have +been stored on the server against the authentication token, which stands +in for a receiver id. The receiver can request a list of tags by making a +GET request to `/tags` with the authentication token in the header: + +##### Request + +~~~~ {.example} +GET /tags HTTP/1.1↵ +RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Host: radiotag.bbc.co.uk↵ +↵ +~~~~ + +##### Response + +The server responds with an Atom feed containing a list of tags created +for this device. + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 1042↵ +↵ + + + Tag List + + + 2011-10-21T13:59:49+01:00 + + BBC + + urn:uuid:8eca1859-bb85-4c23-ba06-d078f6bfc9f5 + 1 + 1 + 1 + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 + 2011-10-21T13:59:49+01:00 + 2011-10-21T13:59:49+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + +~~~~ + +#### Press Tag + +We now show the flow of interactions when a user decides to register +their receiver with the service. The process begins with the user pressing +the `Tag` button as before. + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Content-Length: 43↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +station=0.c224.ce15.ce1.dab&time=1319201989 +~~~~ + +##### Response + +The response in this case is a `201 Created`, since the service supports +receiver tagging and the receiver has passed in the authentication token +with the request to `/tag`. Again the response contains a `identity` +grant. The receiver uses the presence of this grant to decide to display +the option to register. + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 1032↵ +↵ + + + Feedback + + + 2011-10-21T13:59:49+01:00 + + BBC + + urn:uuid:4b8a1b72-f76b-4dc2-9db8-cb15042454ea + 1 + 1 + 1 + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:4b8a1b72-f76b-4dc2-9db8-cb15042454ea + 2011-10-21T13:59:49+01:00 + 2011-10-21T13:59:49+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + +~~~~ + +#### Press Register + +This time the user selects the option to register on the receiver. The +receiver 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. + +##### Request + +~~~~ {.example} +POST /registration_key HTTP/1.1↵ +Content-Length: 73↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a +~~~~ + +##### 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. + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Registration-Key: 399eaa7c↵ +RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵ +↵ +~~~~ + +#### 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 receiver) +> 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 receiver 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. + +#### Enter the PIN + +The user enters the PIN number obtained in the previous step into their +receiver, 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 receiver +tagging is included in the header of the request. This allows the server +to migrate tags from an unpaired receiver to the user's account. + +##### Request + +~~~~ {.example} +POST /register HTTP/1.1↵ +RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Content-Length: 34↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +registration_key=399eaa7c&pin=7535 +~~~~ + +##### Response + +The server checks the credentials and returns `204 No Content` to +indicate that a new token has been created. The response headers contain +the new authentication token (`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 +(`RadioTAG-Account-Name`). This account name can be used by the receiver +to provide a reminder or prompt to the user in case they are unsure of +the account they used to register the receiver. + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Fri, 21 Oct 2011 12:59:50 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +RadioTAG-Account-Name: sean↵ +↵ +~~~~ + +#### Press Tag + +The receiver now has a token which identifies the receiver 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. + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +Content-Length: 43↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +station=0.c224.ce15.ce1.dab&time=1319201990 +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Fri, 21 Oct 2011 12:59:50 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +RadioTAG-Account-Name: sean↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 1032↵ +↵ + + + Feedback + + + 2011-10-21T13:59:50+01:00 + + BBC + + urn:uuid:5967db0e-dc63-428d-a075-90cf316ded5d + 1 + 1 + 1 + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:5967db0e-dc63-428d-a075-90cf316ded5d + 2011-10-21T13:59:50+01:00 + 2011-10-21T13:59:50+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + +~~~~ + +#### Press Tags + +The receiver can again request a list of tags, this time using the new +authentication token. The server has migrated the tags created while the +receiver was unpaired to the user's account, so all three tags created +above are returned in the Atom feed. + +##### Request + +~~~~ {.example} +GET /tags HTTP/1.1↵ +RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +Host: radiotag.bbc.co.uk↵ +↵ +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:50 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +RadioTAG-Account-Name: sean↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 2268↵ +↵ + + + Tag List + + + 2011-10-21T13:59:50+01:00 + + BBC + + urn:uuid:93beb9c2-0b8d-49ad-a813-c1e6120f63b9 + 3 + 1 + 3 + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:5967db0e-dc63-428d-a075-90cf316ded5d + 2011-10-21T13:59:50+01:00 + 2011-10-21T13:59:50+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:4b8a1b72-f76b-4dc2-9db8-cb15042454ea + 2011-10-21T13:59:49+01:00 + 2011-10-21T13:59:49+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + + Feedback + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 + 2011-10-21T13:59:49+01:00 + 2011-10-21T13:59:49+01:00 + Listener views on local radio cuts. Roger hears how to secure inclusion on R4's Last Word. + + +~~~~ + +### Unidentified to user identity + +This section shows the HTTP traces of transactions between a RadioTAG +receiver (e.g. a radio) and a RadioTAG service. It covers the scenario +where the RadioTAG service permits *unidentified* tagging upgradeable +to *user* account tagging, i.e. it provides a response to an +unauthorized receiver but does not store tags until the receiver has +been paired with a user account. + +Here we deal only with the differences between this scenario and the +receiver-to-user scenario above. Please refer to that document for +more information. + +#### Press Tag + +The user presses the `Tag` button. Note that the request is exactly the +same as in the receiver case above. + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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=1319202059 +~~~~ + +##### Response + +The response is a `200 OK` rather than a `201 Created`. The receiver +should remember this result for later as it indicates that the receiver +should resubmit the tag request after registration. + +Note that just like the receiver case, the response contains a +`identity` grant. The receiver can use this to provide the choice to +accept the result or to register the receiver. + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 13:00:59 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 973↵ +↵ + + + The Archers + + + 2011-10-21T14:00:59+01:00 + + BBC + + urn:uuid:3bfaa9dd-11ed-45f9-8f3c-6587db086b04 + 1 + 1 + 1 + + The Archers + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:3bfaa9dd-11ed-45f9-8f3c-6587db086b04 + 2011-10-21T14:00:59+01:00 + 2011-10-21T14:00:59+01:00 + David brings shocking news. + + +~~~~ + +#### Press OK + +At this point, the receiver can forget the stored `200 OK` result code. + +#### Press Tags + +##### Request + +~~~~ {.example} +GET /tags HTTP/1.1↵ +RadioTAG-Auth-Token: ↵ +Host: radiotag.bbc.co.uk↵ +↵ +~~~~ + +##### Response + +As this service does not provide receiver tagging, there are no tags +stored on the server. + +~~~~ {.example} +HTTP/1.1 401 Unauthorized↵ +Date: Fri, 21 Oct 2011 13:00:59 GMT↵ +Status: 401 Unauthorized↵ +RadioTAG-Service-Provider: BBC↵ +Content-Type: text/html;charset=utf-8↵ +Content-Length: 12↵ +↵ +Unauthorized +~~~~ + +#### Press Tag + +##### Request + +~~~~ {.example} +POST /tag HTTP/1.1↵ +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=1319202059 +~~~~ + +##### Response + +Again, the receiver should remember that the return code for this `/tag` +request is 200. + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 13:01:00 GMT↵ +Status: 200 OK↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Grant-Scope: identity↵ +RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 973↵ +↵ + + + The Archers + + + 2011-10-21T14:00:59+01:00 + + BBC + + urn:uuid:8ea43558-70c2-4a4a-aeb9-8ffeee700898 + 1 + 1 + 1 + + The Archers + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:8ea43558-70c2-4a4a-aeb9-8ffeee700898 + 2011-10-21T14:00:59+01:00 + 2011-10-21T14:00:59+01:00 + David brings shocking news. + + +~~~~ + +#### Press Register + +##### Request + +~~~~ {.example} +POST /registration_key HTTP/1.1↵ +Content-Length: 73↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a +~~~~ + +##### Response + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Fri, 21 Oct 2011 13:01:00 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Registration-Key: 4fa9ed43↵ +RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵ +↵ +~~~~ + +#### 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 note on [registering with a web front +end](#register-with-a-web-front-end) above for one possible +implementation. + +#### Enter PIN + +##### Request + +Note that unlike the receiver case, there is no auth token to send. + +~~~~ {.example} +POST /register HTTP/1.1↵ +RadioTAG-Auth-Token: ↵ +Content-Length: 34↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +registration_key=4fa9ed43&pin=9666 +~~~~ + +##### Response + +The receiver has now completed the pairing process so receives an +`RadioTAG-Auth-Token` header which it should include as a request +header in all future requests. + +~~~~ {.example} +HTTP/1.1 204 No Content↵ +Date: Fri, 21 Oct 2011 13:01:00 GMT↵ +Status: 204 No Content↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ +RadioTAG-Account-Name: sean↵ +↵ +~~~~ + +##### Request + +The receiver should have stored the result of the previous request to +`/tag`. As it was a `200 OK` rather than `201 Created`, the receiver knows +it should resubmit the tag request, this time including the newly +acquired `RadioTAG-Auth-Token` in the request header: + +~~~~ {.example} +POST /tag HTTP/1.1↵ +RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ +Content-Length: 43↵ +Content-Type: application/x-www-form-urlencoded↵ +Host: radiotag.bbc.co.uk↵ +↵ +station=0.c224.ce15.ce1.dab&time=1319202060 +~~~~ + +##### 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. + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Fri, 21 Oct 2011 13:01:00 GMT↵ +Status: 201 Created↵ +RadioTAG-Service-Provider: BBC↵ +RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ +RadioTAG-Account-Name: sean↵ +Content-Type: application/xml;charset=utf-8↵ +Content-Length: 973↵ +↵ + + + The Archers + + + 2011-10-21T14:01:00+01:00 + + BBC + + urn:uuid:fcbb6008-aa54-45b4-91c9-78ec0655f9d7 + 1 + 1 + 1 + + The Archers + 0.c224.ce15.ce1.dab + BBC Radio 4 + + + urn:uuid:fcbb6008-aa54-45b4-91c9-78ec0655f9d7 + 2011-10-21T14:01:00+01:00 + 2011-10-21T14:01:00+01:00 + David brings shocking news. + + +~~~~ From 4ef3387e079e40bc3c4e82d4f3adf85bcb6cd3b1 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 12 Feb 2014 15:57:59 +0000 Subject: [PATCH 02/19] Replaced references to receiver with client --- src/radiotag-api-proposal-v1.00d6.md | 210 ++++++++++++++------------- 1 file changed, 107 insertions(+), 103 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index b26d2ad..4e30476 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -27,6 +27,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - 'client' changed to 'receiver' - 'can_register' changed to 'identity' - Draft 6: 2014-02- + - Updated terminology to reflect CPA terms ### URL @@ -36,17 +37,17 @@ Unpublished at time of writing This document specifies version 1.00 of the RadioTAG protocol. -The RadioTAG protocol defines how a receiver (e.g. an IP-enabled radio) +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 receiver obtains authorization to store +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 receiver and server. +responses that pass between the client and server. ## How to read this document @@ -57,7 +58,7 @@ underlying the RadioTAG protocol. These concepts are summarized in the To get an idea of how the RadioTAG protocol works in practice, read the two [narratives](#narratives) in the Appendix. These step through the two most common scenarios to show what is communicated between the -receiver (radio) and the tag service at the HTTP level. This section is +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. @@ -69,10 +70,10 @@ element contains and what limits apply, see [data formats](#data-formats). ## Concepts -A receiver sends a tag request to a tag service, specifying a time and +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 receiver or on the web or be used for another application. +viewed on the client or on the web or be used for another application. ### Service discovery @@ -98,17 +99,17 @@ Format](http://tools.ietf.org/html/rfc4287) as [specified below](#tag-data). A tag response could contain programme, now playing metadata, an advertising message or the response to a call for action. -### Receivers, radios and devices +### Clients, receivers, radios and devices -In this specification, the **receiver** is any device or software program -that implements the receiver side of the RadioTAG specification. While +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. ### The tag service The **tag service** is the web service provided by the broadcaster to -respond to receiver requests. It must implement a number of endpoints +respond to client requests. It must implement a number of endpoints depending on the level of service it provides. ### Levels of identity @@ -116,7 +117,7 @@ depending on the level of service it provides. There are three levels of identity a tag service can provide: - anonymous -- receiver +- client - user *User* in this context refers to an authenticated user account. @@ -131,7 +132,7 @@ Level of identity Tag list on device Tag list on web Account needed ----------------- ------------------ --------------- -------------- Unidentified No No No -Receiver Yes No No +Client Yes No No User Yes Yes Yes @@ -140,13 +141,16 @@ User Yes Yes Yes These levels of identification can be provided in a number of combinations. For example, a service may offer anonymous tagging by default which can be upgraded to user tagging or it may support -tagging out of the box (receiver) with no option to pair the device to +tagging out of the box (client) with no option to pair the device to an online user account. These are the possible combinations: - Unidentified only - Unidentified upgradeable to user -- Receiver only -- Receiver upgradeable to user +- Client only +- Client upgradeable to user + +The client and user levels map directly to the equivalant levels of authentication +offered within the EBU Cross Platform Authentication (CPA) specification. ### No identity @@ -157,18 +161,18 @@ 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 receiver. +so it is not possible to retrieve a list of tags on the client. -### Receiver identity +### Client identity -Receiver identity is designed to provide an "out-of-the-box" +Client identity is designed to provide an "out-of-the-box" experience without the user having to create an account and pair the -receiver. The protocol enables the receiver to become authorized to +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 receiver identity, the server must issue -a `receiver` [grant](#authorization) in response to an unauthorized request +To indicate that it supports client identity, the server must issue +a `client` [grant](#authorization) in response to an unauthorized request to `POST /tag`. It must provide the following endpoints: - [POST /tag](#post-tag) @@ -176,24 +180,24 @@ to `POST /tag`. It must provide the following endpoints: - [GET /tags](#get-tags) Tags are stored on the server. The server must be able to store at least -10 tags per receiver. There is no upper limit. A typical implementation +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 receiver should implement an interface to display the current list of +A client should implement an interface to display the current list of tags associated with it as returned by the `GET /tags` method. -Note that with receiver identification, the receiver stores +Note that with client identification, the client stores a token which uniquely identifies it to the tag service for the -lifetime of that token only. If that identity is reset by the receiver +lifetime of that token only. If that identity is reset by the client deleting the token, any tags which have been submitted against it are effectively orphaned. ### User identity -User identity is where the receiver has been paired to an +User identity is where the client has been paired to an authenticated user's account on a tag service. The same limits apply -as for receiver identification, though a typical implementation will +as for client identification, though a typical implementation will not put any limit on how many tags a user can create. A tag service that enables tagging with a user identity must provide @@ -210,14 +214,14 @@ the following endpoints: 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 receiver needs a -**token**. A valid token authorizes the receiver to perform a specific +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](#post-tag) or [get a list of tags](#get-tags) for either a -[receiver](#receiver-identity) identity or [user](#user-identity) +[client](#client-identity) identity or [user](#user-identity) account identity. -To obtain a token, the receiver must use the **grant** passed back from +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 @@ -230,13 +234,13 @@ attempt to obtain the corresponding token. --------------------------------------------------------------------------------------- Term Definition --------------- -------------------------------------------------------------------- -Receiver The device or user agent which interacts with the RadioTAG service +Client The device or user agent which interacts with the RadioTAG service -Receiver identity A RadioTAG identity associated only with a specific receiver and +Client identity A RadioTAG identity associated only with a specific client and *not* with a user account -User identity A RadioTAG identity where a receiver has been associated with a user - account, and which can then be accessed from any receiver which has +User identity A RadioTAG identity where a client has been associated with a user + account, and which can then be accessed from any client which has been similarly associated Grant Temporary permission to request a service @@ -260,7 +264,7 @@ encoded POST parameters. Responses pass data back in a combination of HTTP headers and XML. While headers are shown here in a canonical form, due to the fact that -proxies and other intermediaries may adjust HTTP headers, both receiver +proxies and other intermediaries may adjust HTTP headers, both client and server implementations should be prepared to accept header *keys* in any mixture of upper and lower case. One common way to handle this is to downcase all header keys on reading. Header *values* on the @@ -278,7 +282,7 @@ RadioTAG-Service-Provider The display name of the tag service provider RadioTAG-Account-Name The display name of the associated user account -RadioTAG-Auth-Token The authorization token for a receiver or user +RadioTAG-Auth-Token The authorization token for a client or user identity -------------------------------------------------------------------------------- @@ -287,9 +291,9 @@ The `RadioTAG-Service-Provider` header should be returned in all responses. The `RadioTAG-Account-Name` should be returned in all responses to -requests made by a receiver that is paired with a user account. +requests made by a client that is paired with a user account. -The `RadioTAG-Auth-Token` header is returned when the receiver has been +The `RadioTAG-Auth-Token` header is returned when the client has been granted authorization. It also enables the tag service to issue a new token to replace an old one - see the next section. @@ -297,14 +301,14 @@ token to replace an old one - see the next section. The tag service can change the `RadioTAG-Auth-Token` in response to any authorized request (i.e. one which contains a valid Auth Token). The -receiver should *always* use the last received Auth Token and update any +client should *always* use the last received Auth Token and update any stored value from that. This provides a way for a tag service to expire tokens. We recommend that tag service implementations allow a period of grace in which an expired token can co-exist with its replacement. This will address the case where the token was updated but the response was not -received by the receiver. +received by the client. ### POST /tag @@ -315,7 +319,7 @@ received by the receiver. -------------------------------------------------------------- Name Value --------------------- --------------------------------------- -RadioTAG-Auth-Token Empty OR receiver token OR user token +RadioTAG-Auth-Token Empty OR client token OR user token -------------------------------------------------------------- @@ -344,7 +348,7 @@ HTTP Status Code HTTP Status Explanation 201 Created The service has stored the requested tag 401 Unauthorized Unidentified tagging is not supported and the token - is blank or does not match either a receiver or + is blank or does not match either a client or user identity -------------------------------------------------------------------------------- @@ -360,7 +364,7 @@ RadioTAG-Auth-Token The token to use from now on. RadioTAG-Account-Name The display name of the associated user account. -RadioTAG-Grant-Scope "receiver" or "identity". See [Authorization](#authorization). +RadioTAG-Grant-Scope "client" or "identity". See [Authorization](#authorization). RadioTAG-Grant-Token The token to use when exercising the grant. @@ -369,8 +373,8 @@ RadioTAG-Grant-Token The token to use when exercising the grant. A grant header is *not* returned in the following cases: - the server supports only unidentified tagging -- the receiver is already using a user identity token -- the receiver is using a receiver identity token and the tag service doesn't +- the client is already using a user identity token +- the client is using a client identity token and the tag service doesn't support user accounts ##### Body @@ -403,7 +407,7 @@ HTTP/1.1 401 Unauthorized↵ Date: Tue, 02 Aug 2011 16:03:24 GMT↵ Status: 401 Unauthorized↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: receiver↵ +RadioTAG-Grant-Scope: client↵ RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 18↵ @@ -411,7 +415,7 @@ Content-Length: 18↵ Must request token ~~~~ -#### Example 2 - `POST /tag` with a valid receiver token +#### Example 2 - `POST /tag` with a valid client token ##### Request @@ -526,7 +530,7 @@ Content-Length: 958↵ Note that the response header does not contain any grants but does contain the paired user account name. -#### Example 4 - `POST /tag` against a service that does not provide receiver tagging +#### Example 4 - `POST /tag` against a service that does not provide client tagging ##### Request @@ -665,7 +669,7 @@ Content-Length: 69↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -grant_scope=receiver&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 +grant_scope=client&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 ~~~~ #### Response @@ -679,7 +683,7 @@ HTTP Status Code HTTP Status Explanation 401 Unauthorized The grant is missing or invalid -403 Forbidden The grant is valid but the receiver is not allowed +403 Forbidden The grant is valid but the client is not allowed to make this request -------------------------------------------------------------------------------- @@ -720,7 +724,7 @@ RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ ----------------------------------------------------- Name Value --------------------- ------------------------------ -RadioTAG-Auth-Token receiver token OR user token +RadioTAG-Auth-Token client token OR user token ----------------------------------------------------- @@ -840,7 +844,7 @@ Content-Length: 974↵ ------------------------------------------------------------- Name Value --------------------- -------------------------------------- -RadioTAG-Auth-Token Either blank or a valid receiver token +RadioTAG-Auth-Token Either blank or a valid client token ------------------------------------------------------------- @@ -918,7 +922,7 @@ RadioTAG-Registration-Url: http://radiotag.example.com/↵ ----------------------------------------------------- Name Value --------------------- ------------------------------ -RadioTAG-Auth-Token Receiver OR user token +RadioTAG-Auth-Token Client OR user token ----------------------------------------------------- @@ -953,7 +957,7 @@ registration_key=2b188492&pin=3612 -------------------------------------------------------------------------------- HTTP Status Code HTTP Status Explanation ---------------- ----------- ------------------------------------------------- -204 No Content The registration has succeeded and the receiver +204 No Content The registration has succeeded and the client has been paired to the associated user account -------------------------------------------------------------------------------- @@ -1189,10 +1193,10 @@ RadioTAG-Service-Provider 16 ## Narratives -### From receiver to user pairing +### From client to user pairing This section describes the requests and responses made between a -receiver and a RadioTAG server when the server supports both receiver +client and a RadioTAG server when the server supports both client and user tagging. #### Tune radio to BBC Radio 4 @@ -1200,7 +1204,7 @@ and user tagging. 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 receiver makes +Having ascertained that the service supports RadioTAG, the client makes available a `Tag` button. #### Press tag @@ -1209,12 +1213,12 @@ The user presses the `Tag` button. ##### Request -The receiver makes a POST request to the tag service with the `station` +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 receiver has no Auth Token, the `Radiotag-Auth-Token` header is +As this client has no Auth Token, the `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. @@ -1232,16 +1236,16 @@ station=0.c224.ce15.ce1.dab&time=1319201989 ##### Response To mitigate the possibility of resource depletion attacks, when the -server supports receiver tagging we introduce a two-step process to +server supports client 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 receiver tagging, it responds to an +When a tag service supports client 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 receiver tagging, and a +which indicates that the server supports client 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 @@ -1252,7 +1256,7 @@ HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ Status: 401 Unauthorized↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: receiver↵ +RadioTAG-Grant-Scope: client↵ RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 18↵ @@ -1262,7 +1266,7 @@ Must request token ##### Request -The receiver POSTs the grant to the `/token` endpoint to request a token +The client POSTs the grant to the `/token` endpoint to request a token to create tags. ~~~~ {.example} @@ -1271,12 +1275,12 @@ Content-Length: 69↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -grant_scope=receiver&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 +grant_scope=client&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 ~~~~ ##### Response -The authentication token is returned to the receiver in the headers of a +The authentication token is returned to the client in the headers of a `204 No Content` response. ~~~~ {.example} @@ -1290,7 +1294,7 @@ RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ ##### Request -Now the receiver has successfully exchanged a grant for a token, the tag +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`. @@ -1357,8 +1361,8 @@ Content-Length: 1032↵ In the previous, successful `/tag` request, the server's response contained a `identity` grant. The presence of this grant indicates -to the receiver that the server supports the pairing a receiver with a user -account. At this stage the receiver can present to the user the option to +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. @@ -1366,9 +1370,9 @@ In this case, we chose the latter by pressing `OK`. #### Press Tags -As the server supports receiver tagging the tags created so far have +As the server supports client tagging the tags created so far have been stored on the server against the authentication token, which stands -in for a receiver id. The receiver can request a list of tags by making a +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: ##### Request @@ -1426,7 +1430,7 @@ Content-Length: 1042↵ #### Press Tag We now show the flow of interactions when a user decides to register -their receiver with the service. The process begins with the user pressing +their client with the service. The process begins with the user pressing the `Tag` button as before. ##### Request @@ -1444,9 +1448,9 @@ station=0.c224.ce15.ce1.dab&time=1319201989 ##### Response The response in this case is a `201 Created`, since the service supports -receiver tagging and the receiver has passed in the authentication token +client tagging and the client has passed in the authentication token with the request to `/tag`. Again the response contains a `identity` -grant. The receiver uses the presence of this grant to decide to display +grant. The client uses the presence of this grant to decide to display the option to register. ~~~~ {.example} @@ -1489,8 +1493,8 @@ Content-Length: 1032↵ #### Press Register -This time the user selects the option to register on the receiver. The -receiver requires an identifier to identify itself to the server during +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. @@ -1532,7 +1536,7 @@ 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 receiver) +> 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. @@ -1544,7 +1548,7 @@ implemented: > form. > > This causes a request to be made to the service which has previously -> stored the registration key that was issued to the receiver in the +> 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. > @@ -1555,12 +1559,12 @@ implemented: #### Enter the PIN The user enters the PIN number obtained in the previous step into their -receiver, which then makes a POST request to `/register` with the +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 receiver +Note that the previously issued authentication token for client tagging is included in the header of the request. This allows the server -to migrate tags from an unpaired receiver to the user's account. +to migrate tags from an unpaired client to the user's account. ##### Request @@ -1581,9 +1585,9 @@ indicate that a new token has been created. The response headers contain the new authentication token (`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 -(`RadioTAG-Account-Name`). This account name can be used by the receiver +(`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 receiver. +the account they used to register the client. ~~~~ {.example} HTTP/1.1 204 No Content↵ @@ -1597,7 +1601,7 @@ RadioTAG-Account-Name: sean↵ #### Press Tag -The receiver now has a token which identifies the receiver with the user +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. @@ -1656,9 +1660,9 @@ Content-Length: 1032↵ #### Press Tags -The receiver can again request a list of tags, this time using the new +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 -receiver was unpaired to the user's account, so all three tags created +client was unpaired to the user's account, so all three tags created above are returned in the Atom feed. ##### Request @@ -1735,20 +1739,20 @@ Content-Length: 2268↵ ### Unidentified to user identity This section shows the HTTP traces of transactions between a RadioTAG -receiver (e.g. a radio) and a RadioTAG service. It covers the scenario +client (e.g. a radio) and a RadioTAG service. It covers the scenario where the RadioTAG service permits *unidentified* tagging upgradeable to *user* account tagging, i.e. it provides a response to an -unauthorized receiver but does not store tags until the receiver has +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 -receiver-to-user scenario above. Please refer to that document for +client-to-user scenario above. Please refer to that document for more information. #### Press Tag The user presses the `Tag` button. Note that the request is exactly the -same as in the receiver case above. +same as in the client case above. ##### Request @@ -1764,13 +1768,13 @@ station=0.c224.ce15.ce1.dab&time=1319202059 ##### Response -The response is a `200 OK` rather than a `201 Created`. The receiver -should remember this result for later as it indicates that the receiver +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 receiver case, the response contains a -`identity` grant. The receiver can use this to provide the choice to -accept the result or to register the receiver. +Note that just like the client case, the response contains a +`identity` grant. The client can use this to provide the choice to +accept the result or to register the client. ~~~~ {.example} HTTP/1.1 200 OK↵ @@ -1812,7 +1816,7 @@ Content-Length: 973↵ #### Press OK -At this point, the receiver can forget the stored `200 OK` result code. +At this point, the client can forget the stored `200 OK` result code. #### Press Tags @@ -1827,7 +1831,7 @@ Host: radiotag.bbc.co.uk↵ ##### Response -As this service does not provide receiver tagging, there are no tags +As this service does not provide client tagging, there are no tags stored on the server. ~~~~ {.example} @@ -1857,7 +1861,7 @@ station=0.c224.ce15.ce1.dab&time=1319202059 ##### Response -Again, the receiver should remember that the return code for this `/tag` +Again, the client should remember that the return code for this `/tag` request is 200. ~~~~ {.example} @@ -1934,7 +1938,7 @@ implementation. ##### Request -Note that unlike the receiver case, there is no auth token to send. +Note that unlike the client case, there is no auth token to send. ~~~~ {.example} POST /register HTTP/1.1↵ @@ -1948,7 +1952,7 @@ registration_key=4fa9ed43&pin=9666 ##### Response -The receiver has now completed the pairing process so receives an +The client has now completed the pairing process so receives an `RadioTAG-Auth-Token` header which it should include as a request header in all future requests. @@ -1964,8 +1968,8 @@ RadioTAG-Account-Name: sean↵ ##### Request -The receiver should have stored the result of the previous request to -`/tag`. As it was a `200 OK` rather than `201 Created`, the receiver knows +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 `RadioTAG-Auth-Token` in the request header: From 6b85ebb55473cb4ae9da282a6fcab4ce7fa21de2 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Thu, 13 Feb 2014 09:36:12 +0000 Subject: [PATCH 03/19] Update makefile to reflect newer draft version filename --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 99f7b42..b6f6694 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -TARGET=radiotag-api-proposal-v1.00d5 +TARGET=radiotag-api-proposal-v1.00d6 SOURCES=src/$(TARGET).md template/default.html html/style.css html/$(TARGET).html: $(SOURCES) pandoc -c style.css --template template/default.html -s --toc src/$(TARGET).md -o html/$(TARGET).html From 7cf6dbab0de4576192729adb3859857b9fc53204 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 19 Feb 2014 17:38:28 +0000 Subject: [PATCH 04/19] First attempt at integrating CPA --- src/radiotag-api-proposal-v1.00d6.md | 774 ++++++++------------------- 1 file changed, 229 insertions(+), 545 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 4e30476..04e7c9c 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -28,6 +28,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - 'can_register' changed to 'identity' - Draft 6: 2014-02- - Updated terminology to reflect CPA terms + - Replaced Tag auth procedure with draft CPA procedure ### URL @@ -112,6 +113,14 @@ 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. +### Authentication + +This proposal does not directly provide an authentication solution. +The tag application should be secured using the processes detailed in +the EBU's Cross Platform Authentication (CPA) specification. This +specification simply aims to highlight the important components and +the direct impact they have on the implementation of tagging. + ### Levels of identity There are three levels of identity a tag service can provide: @@ -150,7 +159,7 @@ an online user account. These are the possible combinations: - Client upgradeable to user The client and user levels map directly to the equivalant levels of authentication -offered within the EBU Cross Platform Authentication (CPA) specification. +offered within the CPA specification. ### No identity @@ -172,13 +181,15 @@ store tags on the server without being associated with an authenticated user account. To indicate that it supports client identity, the server must issue -a `client` [grant](#authorization) in response to an unauthorized request +a `WWW-Authenticate` response-header to an unauthorized request to `POST /tag`. It must provide the following endpoints: - [POST /tag](#post-tag) -- [POST /token](#post-token) - [GET /tags](#get-tags) +In addition it must adhere fully to Client mode within the CPA +specification. + 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 @@ -204,15 +215,12 @@ A tag service that enables tagging with a user identity must provide the following endpoints: - [POST /tag](#post-tag) -- [POST /token](#post-token) - [GET /tags](#get-tags) -- [POST /registration\_key](#post-registration_key) -- [POST /register](#post-register) -### Authorization +In addition it must adhere fully to the User mode within the CPA +specification. -Authorization is based on OAuth 2.0. The central concepts here are -**tokens** and **grants**. +### Authorization To store or retrieve anything at the tag service, a client needs a **token**. A valid token authorizes the client to perform a specific @@ -221,13 +229,8 @@ a tag](#post-tag) or [get a list of tags](#get-tags) for either a [client](#client-identity) identity or [user](#user-identity) account identity. -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. +To obtain a token, the client must follow the process detailed within the +CPA specification. ## Glossary @@ -236,18 +239,18 @@ Term Definition --------------- -------------------------------------------------------------------- Client The device or user agent which interacts with the RadioTAG service -Client identity A RadioTAG identity associated only with a specific client and +Client identity An identity associated only with a specific client and *not* with a user account -User identity A RadioTAG identity where a client has been associated with a user +CPA Cross Platform Authentication, an open stadnard proposed by the EBU + to provide a secure framework for authentication on devices such as + smart radio and televisions. + +User identity An identity where a client has been associated with a user account, and which can then be accessed from any client which has been similarly associated -Grant Temporary permission to request a service - -Scope What a grant applies to - -Auth Token An authorization token which permits you to create a tag +Token An authorization token which permits you to create a tag Unix Time The number of seconds elapsed since midnight Coordinated Universal Time (UTC) on January 1, 1970, not counting leap seconds @@ -280,36 +283,11 @@ Name Value --------------------------- --------------------------------------------------- RadioTAG-Service-Provider The display name of the tag service provider -RadioTAG-Account-Name The display name of the associated user account - -RadioTAG-Auth-Token The authorization token for a client or user - identity - -------------------------------------------------------------------------------- The `RadioTAG-Service-Provider` header should be returned in all responses. -The `RadioTAG-Account-Name` should be returned in all responses to -requests made by a client that is paired with a user account. - -The `RadioTAG-Auth-Token` header is returned when the client has been -granted authorization. It also enables the tag service to issue a new -token to replace an old one - see the next section. - -### Updating tokens - -The tag service can change the `RadioTAG-Auth-Token` in response to -any authorized request (i.e. one which contains a valid Auth Token). The -client should *always* use the last received Auth Token and update any -stored value from that. This provides a way for a tag service to expire -tokens. - -We recommend that tag service implementations allow a period of grace in -which an expired token can co-exist with its replacement. This will -address the case where the token was updated but the response was not -received by the client. - ### POST /tag #### Request @@ -319,7 +297,7 @@ received by the client. -------------------------------------------------------------- Name Value --------------------- --------------------------------------- -RadioTAG-Auth-Token Empty OR client token OR user token +Authorization Not set OR client token OR user token -------------------------------------------------------------- @@ -348,7 +326,7 @@ HTTP Status Code HTTP Status Explanation 201 Created The service has stored the requested tag 401 Unauthorized Unidentified tagging is not supported and the token - is blank or does not match either a client or + is missing or does not match either a client or user identity -------------------------------------------------------------------------------- @@ -360,23 +338,8 @@ Name Value --------------------------- -------------------------------------------------- RadioTAG-Service-Provider The display name of the tag service provider -RadioTAG-Auth-Token The token to use from now on. - -RadioTAG-Account-Name The display name of the associated user account. - -RadioTAG-Grant-Scope "client" or "identity". See [Authorization](#authorization). - -RadioTAG-Grant-Token The token to use when exercising the grant. - ------------------------------------------------------------------------------- -A grant header is *not* returned in the following cases: - -- the server supports only unidentified tagging -- the client is already using a user identity token -- the client is using a client identity token and the tag service doesn't - support user accounts - ##### Body On a successful request (status 200 or 201), the body contains an Atom @@ -392,7 +355,6 @@ explanation of why the request failed. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -405,10 +367,8 @@ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Tue, 02 Aug 2011 16:03:24 GMT↵ -Status: 401 Unauthorized↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "client"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: client↵ -RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 18↵ ↵ @@ -421,7 +381,7 @@ Must request token ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: be222d22-4cef-439e-a77c-c867441dcb33↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -434,10 +394,8 @@ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Tue, 02 Aug 2011 16:03:25 GMT↵ -Status: 201 Created↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 957↵ ↵ @@ -469,9 +427,9 @@ Content-Length: 957↵ ~~~~ -Note that the response header contains the `RadioTAG-Grant-Scope` -`identity`. This will be present only if the service supports user -tagging. +Note that the response header contains the `WWW-Authenticate` header +with a scope value of `user`. This will be present only if the service +supports user tagging. #### Example 3 - `POST /tag` with a valid user token @@ -479,7 +437,7 @@ tagging. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵ +Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -492,10 +450,7 @@ station=0.c224.ce15.ce1.dab&time=1312302129 ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Tue, 02 Aug 2011 16:22:09 GMT↵ -Status: 201 Created↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵ -RadioTAG-Account-Name: sean↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 958↵ ↵ @@ -527,8 +482,8 @@ Content-Length: 958↵ ~~~~ -Note that the response header does not contain any grants but does -contain the paired user account name. +Note that the response header does not contain any `WWW-Authenticate` +headers but does contain the paired user account name. #### Example 4 - `POST /tag` against a service that does not provide client tagging @@ -536,7 +491,6 @@ contain the paired user account name. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -549,10 +503,8 @@ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Mon, 01 Aug 2011 10:38:38 GMT↵ -Status: 200 OK↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 992↵ ↵ @@ -590,7 +542,6 @@ Content-Length: 992↵ ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -603,7 +554,6 @@ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Mon, 01 Aug 2011 10:38:38 GMT↵ -Status: 200 OK↵ RadioTAG-Service-Provider: BBC↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 992↵ @@ -636,84 +586,7 @@ Content-Length: 992↵ ~~~~ -Note that no grant headers are issued. - -### POST /token - -#### Request - -##### Headers - -None. - -##### Parameters - --------------------------------------------------------------------------------- -Name Value ------------- ------------------------------------------------------------------ -grant\_scope The value of the RadioTAG-Grant-Scope provided in the previous - request - -grant\_token The value of the RadioTAG-Grant-Token provided in the previous - request - --------------------------------------------------------------------------------- - -For more information, see [Authorization](#authorization). - -##### Example - -~~~~ {.example} -POST /token HTTP/1.1↵ -Content-Length: 69↵ -Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ -↵ -grant_scope=client&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 -~~~~ - -#### Response - -##### Status - --------------------------------------------------------------------------------- -HTTP Status Code HTTP Status Explanation ----------------- ------------ ------------------------------------------------ -204 No Content The token was successfully created - -401 Unauthorized The grant is missing or invalid - -403 Forbidden The grant is valid but the client is not allowed - to make this request - --------------------------------------------------------------------------------- - -##### Headers - -------------------------------------------------------------------------------- -Name Value ---------------------------- -------------------------------------------------- -RadioTAG-Service-Provider The display name of the tag service provider - -RadioTAG-Auth-Token The newly issued token to use for future requests. - -------------------------------------------------------------------------------- - -##### Body - -The `/token` endpoint should not return any content (as denoted by the -204 status code). - -##### Example - -~~~~ {.example} -HTTP/1.1 204 No Content↵ -Date: Tue, 02 Aug 2011 16:22:08 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ -↵ -~~~~ +Note that no `WWW-Authenticate` headers are issued. ### GET /tags @@ -724,7 +597,7 @@ RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ ----------------------------------------------------- Name Value --------------------- ------------------------------ -RadioTAG-Auth-Token client token OR user token +Authorization client token OR user token ----------------------------------------------------- @@ -755,7 +628,7 @@ specification](http://www.oclc.org/developer/platform/query-responses). ~~~~ {.example} GET /tags HTTP/1.1↵ -RadioTAG-Auth-Token: cf7ce9dc-7762-4b4c-970a-d194c5aa03ed↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -779,18 +652,8 @@ HTTP Status Code HTTP Status Explanation -------------------------------------------------------------------------------- Name Value --------------------------- --------------------------------------------------- -RadioTAG-Account-Name The display name of the associated user account - (if applicable) - RadioTAG-Service-Provider The display name of the tag service provider -RadioTAG-Grant-Scope If the service provides pairing to a user - account, this will have the value `identity`. - See [Authorization](#authorization) - -RadioTAG-Grant-Token The token to use when exercising the `identity` - grant - -------------------------------------------------------------------------------- ##### Body @@ -800,10 +663,8 @@ RadioTAG-Grant-Token The token to use when exercising the `identity` ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Tue, 02 Aug 2011 16:22:08 GMT↵ -Status: 200 OK↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 974↵ ↵ @@ -835,162 +696,6 @@ Content-Length: 974↵ ~~~~ -### POST /registration\_key - -#### Request - -##### Headers - -------------------------------------------------------------- -Name Value ---------------------- -------------------------------------- -RadioTAG-Auth-Token Either blank or a valid client token - -------------------------------------------------------------- - -##### Parameters - --------------------------------------------------------------------- -Name Value ------------- ------------------------------------------------------ -grant\_scope Must be the value `identity` - -grant\_token Must be the grant token issued in the previous request - --------------------------------------------------------------------- - -##### Example - -~~~~ {.example} -POST /registration_key HTTP/1.1↵ -Content-Length: 73↵ -Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ -↵ -grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a -~~~~ - -#### Response - -##### Status - --------------------------------------------------------------------------------- -HTTP Status Code HTTP Status Explanation ----------------- ----------- ------------------------------------------------- -204 No Content The request was successful. The response headers - contain the - registration key required to pair the radio. - --------------------------------------------------------------------------------- - -##### Headers - --------------------------------------------------------------------------------- -Name Value ---------------------------- --------------------------------------------------- -RadioTAG-Service-Provider The display name of the tag service provider - -RadioTAG-Registration-Key The registration key to use when pairing the - device. - -RadioTAG-Registration-Url The url to visit to register the device. - --------------------------------------------------------------------------------- - -##### Body - -This response contains no body. - -##### Example - -~~~~ {.example} -HTTP/1.1 204 No Content↵ -Date: Tue, 02 Aug 2011 16:22:09 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Registration-Key: 2b188492↵ -RadioTAG-Registration-Url: http://radiotag.example.com/↵ -↵ -~~~~ - -### POST /register - -#### Request - -##### Headers - ------------------------------------------------------ -Name Value ---------------------- ------------------------------ -RadioTAG-Auth-Token Client OR user token - ------------------------------------------------------ - -##### Parameters - --------------------------------------------------------------------------------- -Name Value ------------------ ------------------------------------------------------------- -registration\_key The registration key returned from the `/registration_key` - request - -pin The PIN issued to the user (e.g. at a web front end). - --------------------------------------------------------------------------------- - -##### Example - -~~~~ {.example} -POST /register HTTP/1.1↵ -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 -~~~~ - -#### Response - -##### Status - --------------------------------------------------------------------------------- -HTTP Status Code HTTP Status Explanation ----------------- ----------- ------------------------------------------------- -204 No Content The registration has succeeded and the client - has been paired to the associated user account - --------------------------------------------------------------------------------- - -##### Headers - ------------------------------------------------------------------------------- -Name Value ---------------------------- ------------------------------------------------- -RadioTAG-Service-Provider The display name of the tag service provider - -RadioTAG-Auth-Token The token to use for future requests - -RadioTAG-Account-Name The display name of the associated user account - ------------------------------------------------------------------------------- - -##### Body - -There is no body returned in this response. - -##### Example - -~~~~ {.example} -HTTP/1.1 201 Created↵ -Date: Tue, 02 Aug 2011 16:22:09 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: b48bf7ed-14a6-429e-b5c8-35f7a4c094b7↵ -RadioTAG-Account-Name: sean↵ -↵ -~~~~ - ## Data formats ### Tag data @@ -1173,18 +878,6 @@ url 255 See [RFC 2616 Section ----------------------------------------------- Headers Max. size in bytes --------------------------- ------------------ -RadioTAG-Account-Name 48 - -RadioTAG-Auth-Token 48 - -RadioTAG-Grant-Scope 16 - -RadioTAG-Grant-Token 48 - -RadioTAG-Registration-Key 10 - -RadioTAG-Registration-Url 128 - RadioTAG-Service-Provider 16 ----------------------------------------------- @@ -1218,14 +911,13 @@ 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 `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 +As this client has no Auth Token, the `Authorization` 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. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1235,72 +927,111 @@ station=0.c224.ce15.ce1.dab&time=1319201989 ##### Response -To mitigate the possibility of resource depletion attacks, when the -server supports client 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 client 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 client tagging, and a -**token** which is used in the subsequent request to `/token`. +response containing a `WWW-Authenticate` header that advertises the +ability to elevate identity level. -A general principle is that a grant is only guaranteed to be valid on -the next request, so should not be stored permanently. +This header consists of two parts: a **realm** a plain text string +suitable for display in a client UI to indicate an authentication +attempt and a **scope** which is used to inform the client which +method of the CPA specification should be attempted. + +The body contains the JSON object specified in the CPA to inform +the client of the location of the Authorization Provider (AP). ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 401 Unauthorized↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "client"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: client↵ -RadioTAG-Grant-Token: b86bfdfb-5ff5-4cc7-8c61-daaa4804f188↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 18↵ ↵ -Must request token +{ + "error": "unauthorized", + "authorization_uri": "https://ap.bbc.co.uk/authorized", + "service_provider_id": "1" +} ~~~~ ##### Request -The client POSTs the grant to the `/token` endpoint to request a token -to create tags. +As per the CPA specification, the client begins a client level +registration. + +Because it has no client identifiers, it must first request these. ~~~~ {.example} -POST /token HTTP/1.1↵ -Content-Length: 69↵ -Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ +POST /register HTTP/1.1↵ +Content-Length: ↵ +Content-Type: application/json↵ +Host: ap.bbc.co.uk↵ ↵ -grant_scope=client&grant_token=b86bfdfb-5ff5-4cc7-8c61-daaa4804f188 +{ + "client_name": "Revo Axis", + "software_id": "ir-svn", + "software_version": "1.0.0#100443" +} ~~~~ ##### Response -The authentication token is returned to the client in the headers of a -`204 No Content` response. +The client credentials are returned in a JSON response. ~~~~ {.example} -HTTP/1.1 204 No Content↵ +HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Content-Length: 201↵ ↵ +{ + "client_id": "1234", + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "registration_access_token": "askdjfnweiorj134n9gjnr23", + "registration_client_uri": "http://ap.example.com/register" +} ~~~~ ##### 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`. +Now that an identifier and secret have been obtained for the client, +these can be exchanged for a client token. + +~~~~ {.example} +POST /token HTTP/1.1↵ +Content-Length: 58↵ +Content-type: application/x-www-form-urlencoded↵ +Host: ap.bbc.co.uk↵ +↵ +grant_type=authorization_code&client_id=1234&client_secret +~~~~ + +##### Response + +The token is returned in a JSON response object. + +~~~~ {.example} +HTTP/1.1 200 OK +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Content-type: application/json +Cache-control: no-store +Pragma: no-cache + +{ + "token": "alsdkfmasdfn1j23nsfjn1", + "token_type": "bearer" +} +~~~~ + +##### Request + +Now the client has successfully exchanged its credentials for a token, +the tag request can be made again, this time passing the token in a header +of a POST request to `/tag`. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1310,9 +1041,9 @@ station=0.c224.ce15.ce1.dab&time=1319201989 ##### 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 +The server verifies the request by checking the token against it's nominated +authorization provider, 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](http://tools.ietf.org/html/rfc4287) document. See [Data formats](#data-formats) for more details. @@ -1322,10 +1053,8 @@ programme is shown below: ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 201 Created↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 1032↵ ↵ @@ -1360,26 +1089,25 @@ Content-Length: 1032↵ #### Press OK In the previous, successful `/tag` request, the server's response -contained a `identity` 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. +contained an invitation to authenticate at a user level. The presence of +this header 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`. #### Press Tags As the server supports client 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: +been stored on the server against the token. The client can request a list +of tags by making a GET request to `/tags` with the token in the header: ##### Request ~~~~ {.example} GET /tags HTTP/1.1↵ -RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -1392,10 +1120,8 @@ for this device. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 200 OK↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 1042↵ ↵ @@ -1437,7 +1163,7 @@ the `Tag` button as before. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1448,18 +1174,16 @@ station=0.c224.ce15.ce1.dab&time=1319201989 ##### Response The response in this case is a `201 Created`, since the service supports -client tagging and the client has passed in the authentication token -with the request to `/tag`. Again the response contains a `identity` -grant. The client uses the presence of this grant to decide to display -the option to register. +client tagging and the client has passed in the token with the request to +`/tag`. Again the response contains a `WWW-Authenticate` advertisement. The +client uses the presence of this header to decide to display the option to +register. ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 201 Created↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 1032↵ ↵ @@ -1494,109 +1218,111 @@ Content-Length: 1032↵ #### 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. +client needs to follow the steps for obtaining a user access token +detailed in the CPA specification, namely repeating the token step +but this time with a request for a device code. ##### Request ~~~~ {.example} -POST /registration_key HTTP/1.1↵ -Content-Length: 73↵ +POST /token HTTP/1.1↵ +Content-Length: 40↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ +Host: ap.bbc.co.uk↵ ↵ -grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a +response_type=device_code&client_id=1234 ~~~~ ##### 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. +The service responds with a user code and the location of a web +site where the user can complete the registration process. ~~~~ {.example} -HTTP/1.1 204 No Content↵ +HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Registration-Key: 399eaa7c↵ -RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵ +Content-Type: application/json↵ ↵ +{↵ + "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ + "user_code": "Abf13",↵ + "verification_uri": "https://ap.example.com/verify"↵ +} ~~~~ #### 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. +number is outside the scope of both RadioTAG and the CPA specification, +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. +> A typical scenario would be that the user visits the AP's web front +> end, authenticates by some means with the provider (using their user +> name and password, for example), and submits the user code 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. +> stored the user code that was issued to the client in the previous +> step. The service then checks the authenticity and, if valid, +> links the associated client id with user. -#### Enter the PIN +#### Polling to validate registration -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 client -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. +Whilst the user is completing the web front end steps, the client can +begin to poll the AP to see if they have been paired. ##### Request ~~~~ {.example} -POST /register HTTP/1.1↵ -RadioTAG-Auth-Token: e2300af3-bad6-45f8-ba38-6bcb025ca210↵ -Content-Length: 34↵ +POST /token HTTP/1.1↵ +Content-Length: 81↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ +Host: ap.bbc.co.uk↵ ↵ -registration_key=399eaa7c&pin=7535 +grant_type=authorization_code&client_id=1234&code=jkndsfai1324j0fasdkffdsoijgqwer ~~~~ -##### Response +##### Intermediate Response + +Whilst the user is still in the process of registering with the web +front end, the response to this request will indicate a pending state +and advise the client on how soon it should return to ask again. -The server checks the credentials and returns `204 No Content` to -indicate that a new token has been created. The response headers contain -the new authentication token (`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 -(`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. +The same request is repeated each time. ~~~~ {.example} -HTTP/1.1 204 No Content↵ -Date: Fri, 21 Oct 2011 12:59:50 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ -RadioTAG-Account-Name: sean↵ -↵ +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Content-type: application/json↵ +Cache-control: no-store↵ +Pragma: no-cache↵ + +{ +??? +} +~~~~ + +#### Final Response + +When the user has completed the necessary steps on the web front end +and the client is now paired with a user, the AP can return an +appropriate response to the client, which includes a new token that +should replace the previously stored token. + +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Content-type: application/json↵ +Cache-control: no-store↵ +Pragma: no-cache↵ + +{ + "token": "alsdkfmasdfn1j23nsfjn1", + "token_type": "bearer" +} ~~~~ #### Press Tag @@ -1610,7 +1336,7 @@ stored against the user's account. ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1623,10 +1349,7 @@ station=0.c224.ce15.ce1.dab&time=1319201990 ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:50 GMT↵ -Status: 201 Created↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ -RadioTAG-Account-Name: sean↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 1032↵ ↵ @@ -1669,7 +1392,7 @@ above are returned in the Atom feed. ~~~~ {.example} GET /tags HTTP/1.1↵ -RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -1679,10 +1402,7 @@ Host: radiotag.bbc.co.uk↵ ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:50 GMT↵ -Status: 200 OK↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: d7975fbd-343a-474f-9dc4-05752c83cea1↵ -RadioTAG-Account-Name: sean↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 2268↵ ↵ @@ -1758,12 +1478,11 @@ same as in the client case above. ~~~~ {.example} POST /tag HTTP/1.1↵ -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=1319202059 +station=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ ##### Response @@ -1773,16 +1492,14 @@ should remember this result for later as it indicates that the client should resubmit the tag request after registration. Note that just like the client case, the response contains a -`identity` grant. The client can use this to provide the choice to -accept the result or to register the client. +`WWW-Authenticate` header. The client can use this to provide the choice +to accept the result or elevate the client to a user identity level. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 13:00:59 GMT↵ -Status: 200 OK↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 973↵ ↵ @@ -1824,7 +1541,6 @@ At this point, the client can forget the stored `200 OK` result code. ~~~~ {.example} GET /tags HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -1837,7 +1553,7 @@ stored on the server. ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 13:00:59 GMT↵ -Status: 401 Unauthorized↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 12↵ @@ -1851,7 +1567,6 @@ Unauthorized ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1867,10 +1582,8 @@ request is 200. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 13:01:00 GMT↵ -Status: 200 OK↵ +WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Grant-Scope: identity↵ -RadioTAG-Grant-Token: ddc7f510-9353-45ad-9202-746ffe3b663a↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 973↵ ↵ @@ -1904,78 +1617,52 @@ Content-Length: 973↵ #### Press Register +[TODO] Steps to get client credentials + ##### Request ~~~~ {.example} -POST /registration_key HTTP/1.1↵ -Content-Length: 73↵ +POST /token HTTP/1.1↵ +Content-Length: 40↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ +Host: ap.bbc.co.uk↵ ↵ -grant_scope=identity&grant_token=ddc7f510-9353-45ad-9202-746ffe3b663a +response_type=device_code&client_id=1234 ~~~~ ##### Response ~~~~ {.example} -HTTP/1.1 204 No Content↵ -Date: Fri, 21 Oct 2011 13:01:00 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Registration-Key: 4fa9ed43↵ -RadioTAG-Registration-Url: http://radiotag.bbc.co.uk/↵ +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Content-Type: application/json↵ ↵ +{↵ + "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ + "user_code": "Abf13",↵ + "verification_uri": "https://ap.example.com/verify"↵ +} ~~~~ -#### Register with the web front end to get a PIN +#### Register with the web front end Registering with a web front end is outside the scope of the RadioTAG specification. See the note on [registering with a web front end](#register-with-a-web-front-end) above for one possible implementation. -#### Enter PIN - -##### Request - -Note that unlike the client case, there is no auth token to send. - -~~~~ {.example} -POST /register HTTP/1.1↵ -RadioTAG-Auth-Token: ↵ -Content-Length: 34↵ -Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ -↵ -registration_key=4fa9ed43&pin=9666 -~~~~ - -##### Response - -The client has now completed the pairing process so receives an -`RadioTAG-Auth-Token` header which it should include as a request -header in all future requests. - -~~~~ {.example} -HTTP/1.1 204 No Content↵ -Date: Fri, 21 Oct 2011 13:01:00 GMT↵ -Status: 204 No Content↵ -RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ -RadioTAG-Account-Name: sean↵ -↵ -~~~~ +[TODO] Register/polling steps ##### 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 `RadioTAG-Auth-Token` in the request header: +acquired `Authorization` header token value: ~~~~ {.example} POST /tag HTTP/1.1↵ -RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ +Authorization: ???↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1992,10 +1679,7 @@ device and via the web. ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 13:01:00 GMT↵ -Status: 201 Created↵ RadioTAG-Service-Provider: BBC↵ -RadioTAG-Auth-Token: 0f73d1b8-e6b5-451e-9ecf-1a3c33c76415↵ -RadioTAG-Account-Name: sean↵ Content-Type: application/xml;charset=utf-8↵ Content-Length: 973↵ ↵ From d3ac1ed1277f16f8b0deb4dc6a17f73bec89dc4f Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Thu, 20 Feb 2014 14:06:42 +0000 Subject: [PATCH 05/19] Updated some missing CPA specifics --- src/radiotag-api-proposal-v1.00d6.md | 117 ++++++++++++++++++++------- 1 file changed, 87 insertions(+), 30 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 04e7c9c..6c1d237 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -372,7 +372,7 @@ RadioTAG-Service-Provider: BBC↵ Content-Type: text/html;charset=utf-8↵ Content-Length: 18↵ ↵ -Must request token +Must request client token ~~~~ #### Example 2 - `POST /tag` with a valid client token @@ -946,13 +946,8 @@ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "client"↵ RadioTAG-Service-Provider: BBC↵ Content-Type: text/html;charset=utf-8↵ -Content-Length: 18↵ ↵ -{ - "error": "unauthorized", - "authorization_uri": "https://ap.bbc.co.uk/authorized", - "service_provider_id": "1" -} +Must request client token ~~~~ ##### Request @@ -964,7 +959,6 @@ Because it has no client identifiers, it must first request these. ~~~~ {.example} POST /register HTTP/1.1↵ -Content-Length: ↵ Content-Type: application/json↵ Host: ap.bbc.co.uk↵ ↵ @@ -982,7 +976,6 @@ The client credentials are returned in a JSON response. ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Content-Length: 201↵ ↵ { "client_id": "1234", @@ -999,11 +992,14 @@ these can be exchanged for a client token. ~~~~ {.example} POST /token HTTP/1.1↵ -Content-Length: 58↵ Content-type: application/x-www-form-urlencoded↵ Host: ap.bbc.co.uk↵ ↵ -grant_type=authorization_code&client_id=1234&client_secret +{ + "grant_type": "authorization_code", + "client_id": "1234", + "client_secret": "sdalfqealskdfnk13984r2n23klndvs" +} ~~~~ ##### Response @@ -1225,12 +1221,15 @@ but this time with a request for a device code. ##### Request ~~~~ {.example} -POST /token HTTP/1.1↵ -Content-Length: 40↵ +POST /associate HTTP/1.1↵ Content-Type: application/x-www-form-urlencoded↵ Host: ap.bbc.co.uk↵ ↵ -response_type=device_code&client_id=1234 +{ + "client_id": "1234", + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "scope": "sp.example.com" +} ~~~~ ##### Response @@ -1242,6 +1241,8 @@ site where the user can complete the registration process. HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ Content-Type: application/json↵ +Cache-Control: no-store↵ +Pragma: no-cache↵ ↵ {↵ "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ @@ -1278,11 +1279,14 @@ begin to poll the AP to see if they have been paired. ~~~~ {.example} POST /token HTTP/1.1↵ -Content-Length: 81↵ -Content-Type: application/x-www-form-urlencoded↵ Host: ap.bbc.co.uk↵ +Content-type: application/json↵ ↵ -grant_type=authorization_code&client_id=1234&code=jkndsfai1324j0fasdkffdsoijgqwer +{ + "grant_type": "authorization_code", + "client_id": "1234", + "device_code": "jkndsfai1324j0fasdkffdsoijgqwer" +} ~~~~ ##### Intermediate Response @@ -1301,10 +1305,11 @@ Cache-control: no-store↵ Pragma: no-cache↵ { -??? } ~~~~ +[TODO] Body is currently undefined in CPA draft + #### Final Response When the user has completed the necessary steps on the web front end @@ -1320,8 +1325,10 @@ Cache-control: no-store↵ Pragma: no-cache↵ { + "user_display_name": "Alice", "token": "alsdkfmasdfn1j23nsfjn1", - "token_type": "bearer" + "token_type": "bearer", + "scope": "sp.example.com" } ~~~~ @@ -1556,9 +1563,8 @@ Date: Fri, 21 Oct 2011 13:00:59 GMT↵ WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ RadioTAG-Service-Provider: BBC↵ Content-Type: text/html;charset=utf-8↵ -Content-Length: 12↵ ↵ -Unauthorized +Must request user token ~~~~ #### Press Tag @@ -1617,25 +1623,64 @@ Content-Length: 973↵ #### Press Register -[TODO] Steps to get client credentials - ##### Request +As per the CPA specification, the client begins a client level +registration. + +Because it has no client identifiers, it must first request these. + ~~~~ {.example} -POST /token HTTP/1.1↵ -Content-Length: 40↵ -Content-Type: application/x-www-form-urlencoded↵ +POST /register HTTP/1.1↵ +Content-Type: application/json↵ Host: ap.bbc.co.uk↵ ↵ -response_type=device_code&client_id=1234 +{ + "client_name": "Revo Axis", + "software_id": "ir-svn", + "software_version": "1.0.0#100443" +} +~~~~ + +##### Response + +The client credentials are returned in a JSON response. + +~~~~ {.example} +HTTP/1.1 201 Created↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +↵ +{ + "client_id": "1234", + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "registration_access_token": "askdjfnweiorj134n9gjnr23", + "registration_client_uri": "http://ap.example.com/register" +} +~~~~ + +##### Request + +Now that an identifier and secret have been obtained for the client, +the client can begin user mode association. + +~~~~ {.example} +POST /associate HTTP/1.1↵ +Content-type: application/json↵ +↵ +{↵ + "client_id": "1234",↵ + "client_secret": "sdalfqealskdfnk13984r2n23klndvs",↵ + "scope": "sp.example.com"↵ +} ~~~~ ##### Response ~~~~ {.example} HTTP/1.1 200 OK↵ -Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Content-Type: application/json↵ +Content-type: application/json↵ +Cache-Control: no-store↵ +Pragma: no-cache↵ ↵ {↵ "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ @@ -1651,7 +1696,19 @@ specification. See the note on [registering with a web front end](#register-with-a-web-front-end) above for one possible implementation. -[TODO] Register/polling steps +#### Poll for token + +Whilst the user is dealing with the web front end, the client should +poll for a token which will return in the event of the user completing +the necessary steps on the web front end. + +##### Request + +x + +##### Response + +y ##### Request From 98f43c10566b0d72f9b2b21a2552c8bd57a74d8e Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Tue, 25 Feb 2014 13:04:08 +0000 Subject: [PATCH 06/19] Further clarifications, added missing flows --- src/radiotag-api-proposal-v1.00d6.md | 80 +++++++++++++++++++--------- 1 file changed, 56 insertions(+), 24 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 6c1d237..c204772 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -43,8 +43,9 @@ 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 +The protocol defines how the Cross Platform Authentication (CPA) protocol is +implemented within this protocol, to allow the client to obtain 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 @@ -115,11 +116,10 @@ depending on the level of service it provides. ### Authentication -This proposal does not directly provide an authentication solution. -The tag application should be secured using the processes detailed in -the EBU's Cross Platform Authentication (CPA) specification. This -specification simply aims to highlight the important components and -the direct impact they have on the implementation of tagging. +This proposal does not directly provide an authentication solution. The tag +application should be secured using the processes detailed in the CPA +specification. This specification simply aims to highlight the important +components and the direct impact they have on the implementation of tagging. ### Levels of identity @@ -180,9 +180,9 @@ 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 client identity, the server must issue -a `WWW-Authenticate` response-header to an unauthorized request -to `POST /tag`. It must provide the following endpoints: +To indicate that it supports client identity, the server must issue a +`WWW-Authenticate` response-header with a `client` scope to an unauthorized +request to `POST /tag`. It must provide the following endpoints: - [POST /tag](#post-tag) - [GET /tags](#get-tags) @@ -198,9 +198,8 @@ 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. -Note that with client identification, the client stores -a token which uniquely identifies it to the tag service for the -lifetime of that token only. If that identity is reset by the client +Note that with client identification, the client stores a token which uniquely +identifies it to the tag service. If that identity is reset by the client deleting the token, any tags which have been submitted against it are effectively orphaned. @@ -336,6 +335,10 @@ HTTP Status Code HTTP Status Explanation ------------------------------------------------------------------------------- Name Value --------------------------- -------------------------------------------------- +WWW-Authenticate Not set OR CPA response header to indicate + requirement or optional ability to change + authorization mode beyond current state + RadioTAG-Service-Provider The display name of the tag service provider ------------------------------------------------------------------------------- @@ -918,6 +921,7 @@ authentication token. ~~~~ {.example} POST /tag HTTP/1.1↵ +Authorization:↵ Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1247,7 +1251,9 @@ Pragma: no-cache↵ {↵ "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ "user_code": "Abf13",↵ - "verification_uri": "https://ap.example.com/verify"↵ + "verification_uri": "https://ap.example.com/verify",↵ + "expires_in": 1800, + "interval": 5↵ } ~~~~ @@ -1273,7 +1279,10 @@ implemented: #### Polling to validate registration Whilst the user is completing the web front end steps, the client can -begin to poll the AP to see if they have been paired. +begin to poll the AP to see if they have been paired. The request should be +repeated, at most, as frequently as the `interval` duration advises. + +Polling should be attempted for no longer than the `expires_in` duration. ##### Request @@ -1292,24 +1301,22 @@ Content-type: application/json↵ ##### Intermediate Response Whilst the user is still in the process of registering with the web -front end, the response to this request will indicate a pending state -and advise the client on how soon it should return to ask again. +front end, the response to this request will indicate a pending state. The same request is repeated each time. ~~~~ {.example} -HTTP/1.1 200 OK↵ +HTTP/1.1 400 Bad Request↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ Content-type: application/json↵ Cache-control: no-store↵ Pragma: no-cache↵ { + "error": "authorization_pending" } ~~~~ -[TODO] Body is currently undefined in CPA draft - #### Final Response When the user has completed the necessary steps on the web front end @@ -1686,6 +1693,8 @@ Pragma: no-cache↵ "device_code": "jkndsfai1324j0fasdkffdsoijgqwer",↵ "user_code": "Abf13",↵ "verification_uri": "https://ap.example.com/verify"↵ + "expires_in": 1800↵ + "interval": 5↵ } ~~~~ @@ -1699,16 +1708,39 @@ implementation. #### Poll for token Whilst the user is dealing with the web front end, the client should -poll for a token which will return in the event of the user completing -the necessary steps on the web front end. +poll for a token at the rate indicated in the `interval` which will return in +the event of the user completing the necessary steps on the web front end. ##### Request -x +~~~~ {.example} +POST /token HTTP/1.1↵ +Content-type: application/x-www-form-urlencoded↵ +Host: ap.bbc.co.uk↵ +↵ +{↵ + "grant_type": "authorization_code",↵ + "client_id": "1234",↵ + "device_code": "jkndsfai1324j0fasdkffdsoijgqwer"↵ +}↵ +~~~~ ##### Response -y +~~~~ {.example} +HTTP/1.1 200 OK↵ +Date: Fri, 21 Oct 2011 12:59:49 GMT↵ +Content-type: application/json↵ +Cache-control: no-store↵ +Pragma: no-cache↵ + +{ + "user_display_name": "Alice", + "token": "alsdkfmasdfn1j23nsfjn1", + "token_type": "bearer", + "scope": "sp.example.com" +} +~~~~ ##### Request From 1c8693984eb05ff81a112bc236e569360b8139a0 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 12 Mar 2014 16:59:26 +0000 Subject: [PATCH 07/19] Updated to latest CPA draft, added RadioDNS discovery, TLS, general tidy up --- src/radiotag-api-proposal-v1.00d6.md | 370 ++++++++++++--------------- 1 file changed, 167 insertions(+), 203 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index c204772..71241f4 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -1,6 +1,6 @@ % RadioTAG 1.00 specification, draft 6 % Sean O'Halpin (BBC R&D); Chris Lowis (BBC R&D) -% 2014-02- +% 2014-03- ## Front matter ### Authors @@ -26,9 +26,13 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - 'paired' changed to 'user (identity)' - 'client' changed to 'receiver' - 'can_register' changed to 'identity' -- Draft 6: 2014-02- +- Draft 6: 2014-03- - Updated terminology to reflect CPA terms - Replaced Tag auth procedure with draft CPA procedure + - Updated and simplified req/rep examples, ensured compliance with latest + CPA draft, made FQDN and URLs consistent across examples + - Added RadioDNS discovery + - Added recommendation for TLS (HTTPS) ### URL @@ -77,13 +81,42 @@ 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. -### Service discovery +### Application discovery -[TODO] RadioDNS lookup. +A client must be capable of resolving the authorative FQDN for a service via the +methdology defined in the RadioDNS specification. + +Application lookup may then be performed against this FQDN by means of a DNS SRV +Record request using the service name `radiotag`. + +If at least one SRV record is successfully resolved, this service supports the +RadioTAG application, accessed on the host and port indicated in the relevant +SRV record. For example, for a query made to: + + _radiotag._tcp.bbc.co.uk. + +Using the nslookup tool, this would yield the following SRV record: + + service = 0 100 80 radiotag.bbc.co.uk. + +This indicates that the RadioTAG application can be accessed on the FQDN +radiotag.bbc.co.uk, port 80. + +Note that more than one SRV record may be returned with differing values. This +can be used for load balancing purposes by providing different FQDNs/Ports with +different priorities/weightings. See the SRV record specification for a more +detailed explanation on handling SRV resolution results. ### HTTPS -[TODO] All API calls must use HTTPS. +Any implementation of RadioTAG MUST require the use of Transport Layer Security +(TLS). + +The appropriate version (or versions) of TLS will vary over time, based on the +widespread deployment and known security vulnerabilities. + +Implementations MAY also support additional transport-layer security mechanisms +that meet their security requirements. ### Tag requests @@ -112,7 +145,7 @@ an application running on a mobile phone or in a web browser. 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. +depending on the authorization modes it provides. ### Authentication @@ -121,36 +154,36 @@ application should be secured using the processes detailed in the CPA specification. This specification simply aims to highlight the important components and the direct impact they have on the implementation of tagging. -### Levels of identity +### Authorization modes -There are three levels of identity a tag service can provide: +There are three modes a tag service can provide: -- anonymous +- unidentified - client - user *User* in this context refers to an authenticated user account. -The levels of identification are distinguished by whether or not tags +The authorization modes are distinguished by whether or not tags are retrievable on the device or on the web and by whether you need a user account on the broadcaster's web service. The table below summarizes the differences: ---------------------------------------------------------------------- -Level of identity Tag list on device Tag list on web Account needed ------------------ ------------------ --------------- -------------- -Unidentified No No No +----------------------------------------------------------------------- +Authorization mode Tag list on device Tag list on web Account needed +------------------ ------------------ --------------- -------------- +Unidentified No No No -Client Yes No No +Client Yes No No -User Yes Yes Yes +User Yes Yes Yes ---------------------------------------------------------------------- +----------------------------------------------------------------------- -These levels of identification can be provided in a number of -combinations. For example, a service may offer anonymous tagging by -default which can be upgraded to user tagging or it may support -tagging out of the box (client) with no option to pair the device to +These authorization modes can be provided in a number of +combinations. For example, a service may offer unidentified tagging by +default which can be upgraded to user mode tagging or it may support +tagging out of the box (client mode) with no option to pair the device to an online user account. These are the possible combinations: - Unidentified only @@ -158,12 +191,17 @@ an online user account. These are the possible combinations: - Client only - Client upgradeable to user -The client and user levels map directly to the equivalant levels of authentication +The client and user modes map directly to the equivalant authorization modes offered within the CPA specification. +There is no defined combination to upgrade from unidentified to client mode. +This is an automated operation, no end user input is proposed in this process. +Any client capable of upgrading to client mode will do so automatically and +therefore never originate in an unidentified state. + ### No identity -Unidentified tagging is the minimal level of service. The broadcaster must +Unidentified tagging is the minimal mode of service. The broadcaster must provide the following endpoint: - [POST /tag](#post-tag) @@ -172,7 +210,7 @@ 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. -### Client identity +### Client mode Client identity is designed to provide an "out-of-the-box" experience without the user having to create an account and pair the @@ -181,7 +219,7 @@ store tags on the server without being associated with an authenticated user account. To indicate that it supports client identity, the server must issue a -`WWW-Authenticate` response-header with a `client` scope to an unauthorized +`WWW-Authenticate` response-header with a `client` mode to an unauthorized request to `POST /tag`. It must provide the following endpoints: - [POST /tag](#post-tag) @@ -203,7 +241,7 @@ identifies it to the tag service. If that identity is reset by the client deleting the token, any tags which have been submitted against it are effectively orphaned. -### User identity +### User mode User identity is where the client has been paired to an authenticated user's account on a tag service. The same limits apply @@ -275,18 +313,6 @@ as is. UTF-8 is the only supported character set. -### Common response headers - --------------------------------------------------------------------------------- -Name Value ---------------------------- --------------------------------------------------- -RadioTAG-Service-Provider The display name of the tag service provider - --------------------------------------------------------------------------------- - -The `RadioTAG-Service-Provider` header should be returned in all -responses. - ### POST /tag #### Request @@ -339,8 +365,6 @@ WWW-Authenticate Not set OR CPA response header to indicate requirement or optional ability to change authorization mode beyond current state -RadioTAG-Service-Provider The display name of the tag service provider - ------------------------------------------------------------------------------- ##### Body @@ -358,9 +382,8 @@ explanation of why the request failed. ~~~~ {.example} POST /tag HTTP/1.1↵ -Content-Length: 43↵ -Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ +Content-Type: application/x-www-form-urlencoded↵ ↵ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ @@ -370,10 +393,8 @@ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Tue, 02 Aug 2011 16:03:24 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "client"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ Content-Type: text/html;charset=utf-8↵ -Content-Length: 18↵ ↵ Must request client token ~~~~ @@ -384,10 +405,9 @@ Must request client token ~~~~ {.example} POST /tag HTTP/1.1↵ +Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ -Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ ↵ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ @@ -397,17 +417,15 @@ station=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Tue, 02 Aug 2011 16:03:25 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 957↵ ↵ PM - - + + 2011-08-02T17:03:24+01:00 BBC @@ -431,7 +449,7 @@ Content-Length: 957↵ ~~~~ Note that the response header contains the `WWW-Authenticate` header -with a scope value of `user`. This will be present only if the service +with a `user` modes value. This will be present only if the service supports user tagging. #### Example 3 - `POST /tag` with a valid user token @@ -440,10 +458,9 @@ supports user tagging. ~~~~ {.example} POST /tag HTTP/1.1↵ +Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ -Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ ↵ station=0.c224.ce15.ce1.dab&time=1312302129 ~~~~ @@ -453,16 +470,14 @@ station=0.c224.ce15.ce1.dab&time=1312302129 ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Tue, 02 Aug 2011 16:22:09 GMT↵ -RadioTAG-Service-Provider: BBC↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 958↵ ↵ PM - - + + 2011-08-02T17:22:09+01:00 BBC @@ -494,9 +509,8 @@ headers but does contain the paired user account name. ~~~~ {.example} POST /tag HTTP/1.1↵ -Content-Length: 43↵ -Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ +Content-Type: application/x-www-form-urlencoded↵ ↵ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ @@ -506,17 +520,15 @@ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Mon, 01 Aug 2011 10:38:38 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 992↵ ↵ Meet David Sedaris - - + + 2011-08-01T11:38:38+01:00 BBC @@ -545,9 +557,8 @@ Content-Length: 992↵ ~~~~ {.example} POST /tag HTTP/1.1↵ -Content-Length: 43↵ -Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ +Content-Type: application/x-www-form-urlencoded↵ ↵ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ @@ -557,16 +568,14 @@ station=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Mon, 01 Aug 2011 10:38:38 GMT↵ -RadioTAG-Service-Provider: BBC↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 992↵ ↵ Meet David Sedaris - - + + 2011-08-01T11:38:38+01:00 BBC @@ -631,8 +640,8 @@ specification](http://www.oclc.org/developer/platform/query-responses). ~~~~ {.example} GET /tags HTTP/1.1↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Host: radiotag.bbc.co.uk↵ +Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ ↵ ~~~~ @@ -650,15 +659,6 @@ HTTP Status Code HTTP Status Explanation -------------------------------------------------------------------------------- -##### Headers - --------------------------------------------------------------------------------- -Name Value ---------------------------- --------------------------------------------------- -RadioTAG-Service-Provider The display name of the tag service provider - --------------------------------------------------------------------------------- - ##### Body ##### Example @@ -666,17 +666,15 @@ RadioTAG-Service-Provider The display name of the tag service provider ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Tue, 02 Aug 2011 16:22:08 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 974↵ ↵ Tag List - - + + 2011-08-02T17:22:08+01:00 BBC @@ -753,7 +751,7 @@ radiotag:sid RadioDNS service identifier 32 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). +to the client/user (i.e. scoped by the auth mode). 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 @@ -773,8 +771,8 @@ The example below shows these elements in context: Meet David Sedaris - - + + 2011-08-01T11:38:38+01:00 BBC @@ -804,8 +802,8 @@ The example below shows these elements in context: Tag List - - + + 2011-08-02T17:22:09+01:00 BBC @@ -876,15 +874,6 @@ url 255 See [RFC 2616 Section ---------------------------------------------------------------------------------------------- -### HTTP Headers - ------------------------------------------------ -Headers Max. size in bytes ---------------------------- ------------------ -RadioTAG-Service-Provider 16 - ------------------------------------------------ - # Appendix ## Narratives @@ -921,10 +910,9 @@ authentication token. ~~~~ {.example} POST /tag HTTP/1.1↵ +Host: radiotag.bbc.co.uk↵ Authorization:↵ -Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ -Host: radiotag.bbc.co.uk↵ ↵ station=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ @@ -934,21 +922,19 @@ station=0.c224.ce15.ce1.dab&time=1319201989 When a tag service supports client tagging, it responds to an unauthenticated `/tag` request by returning a `401 Unauthorized` response containing a `WWW-Authenticate` header that advertises the -ability to elevate identity level. - -This header consists of two parts: a **realm** a plain text string -suitable for display in a client UI to indicate an authentication -attempt and a **scope** which is used to inform the client which -method of the CPA specification should be attempted. +ability to upgrade authorization mode. -The body contains the JSON object specified in the CPA to inform -the client of the location of the Authorization Provider (AP). +This header consists of three parts: `name`, a plain text string +suitable for display in a client UI to indicate who or what the client +is attempting to authorize with or for, a `uri` which provides the +base or prefix to all CPA endpoint URLs, and `mode` which is used to +inform the client which upgradable modes of the CPA specification are +supported by this auth provider. ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "client"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ Content-Type: text/html;charset=utf-8↵ ↵ Must request client token @@ -956,15 +942,14 @@ Must request client token ##### Request -As per the CPA specification, the client begins a client level -registration. +As per the CPA specification, the client begins a client mode registration. Because it has no client identifiers, it must first request these. ~~~~ {.example} POST /register HTTP/1.1↵ -Content-Type: application/json↵ Host: ap.bbc.co.uk↵ +Content-Type: application/json↵ ↵ { "client_name": "Revo Axis", @@ -983,9 +968,7 @@ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ ↵ { "client_id": "1234", - "client_secret": "sdalfqealskdfnk13984r2n23klndvs", - "registration_access_token": "askdjfnweiorj134n9gjnr23", - "registration_client_uri": "http://ap.example.com/register" + "client_secret": "sdalfqealskdfnk13984r2n23klndvs" } ~~~~ @@ -996,13 +979,14 @@ these can be exchanged for a client token. ~~~~ {.example} POST /token HTTP/1.1↵ -Content-type: application/x-www-form-urlencoded↵ Host: ap.bbc.co.uk↵ +Content-type: application/x-www-form-urlencoded↵ ↵ { - "grant_type": "authorization_code", + "grant_type": "authorization_code" "client_id": "1234", - "client_secret": "sdalfqealskdfnk13984r2n23klndvs" + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "scope": "radiotag.bbc.co.uk" } ~~~~ @@ -1011,15 +995,18 @@ Host: ap.bbc.co.uk↵ The token is returned in a JSON response object. ~~~~ {.example} -HTTP/1.1 200 OK +HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -Content-type: application/json -Cache-control: no-store -Pragma: no-cache - +Content-type: application/json↵ +Cache-control: no-store↵ +Pragma: no-cache↵ +↵ { + "description": "RadioTAG token for user Alice", + "short_description": "Alice", "token": "alsdkfmasdfn1j23nsfjn1", - "token_type": "bearer" + "token_type": "bearer", + "scope": "radiotag.bbc.co.uk" } ~~~~ @@ -1032,7 +1019,6 @@ of a POST request to `/tag`. ~~~~ {.example} POST /tag HTTP/1.1↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ -Content-Length: 43↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ @@ -1053,10 +1039,8 @@ programme is shown below: ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA auth_uri="https://www.bbc.co.uk/id/device/token" "user"↵ -RadioTAG-Service-Provider: BBC↵ +WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ -Content-Length: 1032↵ ↵ Date: Mon, 1 Jun 2015 13:04:20 +0100 Subject: [PATCH 08/19] Moved all endpoints in to RadioDNS-standardised path ETSI standardisation of RadioEPG in to an ETSI specification introduced a versioned path for locating IP-based documents. The RadioVIS part of the Slideshow specification also has a similar path for it's endpoint. By using a path we avoid the potential of conflicting with other endpoints on a multi-purpose server. The inclusion of a version number also makes future development of the specification easier to manage without breaking legacy implementations. --- src/radiotag-api-proposal-v1.00d6.md | 46 ++++++++++++++++------------ 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 71241f4..76ff021 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -1,6 +1,6 @@ % RadioTAG 1.00 specification, draft 6 % Sean O'Halpin (BBC R&D); Chris Lowis (BBC R&D) -% 2014-03- +% 2015-06- ## Front matter ### Authors @@ -26,13 +26,14 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - 'paired' changed to 'user (identity)' - 'client' changed to 'receiver' - 'can_register' changed to 'identity' -- Draft 6: 2014-03- +- Draft 6: 2015-06- - Updated terminology to reflect CPA terms - Replaced Tag auth procedure with draft CPA procedure - Updated and simplified req/rep examples, ensured compliance with latest CPA draft, made FQDN and URLs consistent across examples - Added RadioDNS discovery - Added recommendation for TLS (HTTPS) + - Moved all endpoints in to RadioDNS-standardised path ### URL @@ -147,6 +148,11 @@ 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 authorization modes it provides. +### Base path + +All end points defined in this document are intended to be located on the tag +service host within the base path `/radiodns/tag/1/` + ### Authentication This proposal does not directly provide an authentication solution. The tag @@ -381,7 +387,7 @@ explanation of why the request failed. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ @@ -404,7 +410,7 @@ Must request client token ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ @@ -457,7 +463,7 @@ supports user tagging. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Type: application/x-www-form-urlencoded↵ @@ -508,7 +514,7 @@ headers but does contain the paired user account name. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ @@ -556,7 +562,7 @@ Content-Type: application/xml;charset=utf-8↵ ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ @@ -639,7 +645,7 @@ specification](http://www.oclc.org/developer/platform/query-responses). ##### Example ~~~~ {.example} -GET /tags HTTP/1.1↵ +GET /radiodns/tag/1/tags HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ ↵ @@ -909,7 +915,7 @@ events is also triggered when the request contains an invalid authentication token. ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization:↵ Content-Type: application/x-www-form-urlencoded↵ @@ -947,7 +953,7 @@ As per the CPA specification, the client begins a client mode registration. Because it has no client identifiers, it must first request these. ~~~~ {.example} -POST /register HTTP/1.1↵ +POST /radiodns/tag/1/register HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-Type: application/json↵ ↵ @@ -978,7 +984,7 @@ Now that an identifier and secret have been obtained for the client, these can be exchanged for a client token. ~~~~ {.example} -POST /token HTTP/1.1↵ +POST /radiodns/tag/1/token HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-type: application/x-www-form-urlencoded↵ ↵ @@ -1017,7 +1023,7 @@ the tag request can be made again, this time passing the token in a header of a POST request to `/tag`. ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1090,7 +1096,7 @@ of tags by making a GET request to `/tags` with the token in the header: ##### Request ~~~~ {.example} -GET /tags HTTP/1.1↵ +GET /radiodns/tag/1/tags HTTP/1.1↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Host: radiotag.bbc.co.uk↵ ↵ @@ -1144,7 +1150,7 @@ the `Tag` button as before. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ @@ -1265,7 +1271,7 @@ Polling should be attempted for no longer than the `expires_in` duration. ##### Request ~~~~ {.example} -POST /token HTTP/1.1↵ +POST /radiodns/tag/1/token HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-type: application/json↵ ↵ @@ -1329,7 +1335,7 @@ stored against the user's account. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ @@ -1382,7 +1388,7 @@ above are returned in the Atom feed. ##### Request ~~~~ {.example} -GET /tags HTTP/1.1↵ +GET /radiodns/tag/1/tags HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ ↵ @@ -1466,7 +1472,7 @@ same as in the client case above. ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ @@ -1526,7 +1532,7 @@ At this point, the client can forget the stored `200 OK` result code. ##### Request ~~~~ {.example} -GET /tags HTTP/1.1↵ +GET /radiodns/tag/1/tags HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -1550,7 +1556,7 @@ Must request user token ##### Request ~~~~ {.example} -POST /tag HTTP/1.1↵ +POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ From 2d36ddd5c2eb325d67185fd691d2ff2351d5547c Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 13:48:54 +0100 Subject: [PATCH 09/19] Changed references from 'station' to 'radio service' or 'bearer' RadioDNS and ETSI specifications commonly refer to radio stations as "radio services". The specific "station" param in HTTP POSTs is actually a Bearer definition, therefore it has been changed to "bearer". --- src/radiotag-api-proposal-v1.00d6.md | 54 ++++++++++++++-------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 76ff021..abf4e06 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -34,6 +34,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - Added RadioDNS discovery - Added recommendation for TLS (HTTPS) - Moved all endpoints in to RadioDNS-standardised path + - Changed references from 'station' to 'radio service' or 'bearer' ### URL @@ -46,7 +47,7 @@ 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. +and radio service being listened to. The protocol defines how the Cross Platform Authentication (CPA) protocol is implemented within this protocol, to allow the client to obtain authorization to @@ -78,7 +79,7 @@ element contains and what limits apply, see [data formats](#data-formats). ## 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 +radio service. 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. @@ -121,9 +122,9 @@ that meet their security requirements. ### 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. +A tag *request* specifies a time and bearer. The time is specified +using seconds since Jan 1 1970, i.e. the Unix epoch. The bearer is +specified using the bearerURI format defined in ETSI TS 103 270. How that information is interpreted is up to the broadcaster. @@ -212,7 +213,7 @@ provide the following endpoint: - [POST /tag](#post-tag) -A `POST` to this endpoint should return metadata relevant to the station +A `POST` to this endpoint should return metadata relevant to the radio service 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. @@ -335,12 +336,12 @@ Authorization Not set OR client token OR user token ##### Parameters -------------------------------------------------------------------------------- -Name Value -------- ----------------------------------------------------------------------- -station RadioDNS broadcast parameters joined with dots, e.g. - "0.c224.ce15.ce1.dab" +Name Value +------ ------------------------------------------------------------------------ +bearer RadioDNS broadcast parameters joined with dots, e.g. + "0.c224.ce15.ce1.dab" -time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) +time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) -------------------------------------------------------------------------------- @@ -391,7 +392,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1312301004 +bearer=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ ##### Response @@ -415,7 +416,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1312301004 +bearer=0.c224.ce15.ce1.dab&time=1312301004 ~~~~ ##### Response @@ -468,7 +469,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1312302129 +bearer=0.c224.ce15.ce1.dab&time=1312302129 ~~~~ ##### Response @@ -518,7 +519,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1312195118 +bearer=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ ##### Response @@ -566,7 +567,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1312195118 +bearer=0.c224.ce15.ce1.dab&time=1312195118 ~~~~ ##### Response @@ -904,9 +905,8 @@ The user presses the `Tag` button. ##### 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` +The client makes a POST request to the tag service with the `bearer` +identifier, and a `time`. Unix Time is used for the `time` parameter. As this client has no Auth Token, the `Authorization` header is blank. @@ -920,7 +920,7 @@ Host: radiotag.bbc.co.uk↵ Authorization:↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ ##### Response @@ -1028,7 +1028,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ ##### Response @@ -1083,7 +1083,7 @@ contained an invitation to upgrade to user mode. The presence of this header 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 the current tag and return to the default state for the radio service. In this case, we chose the latter by pressing `OK`. @@ -1155,7 +1155,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ ##### Response @@ -1340,7 +1340,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319201990 +bearer=0.c224.ce15.ce1.dab&time=1319201990 ~~~~ ##### Response @@ -1476,7 +1476,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989 ~~~~ ##### Response @@ -1560,7 +1560,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319202059 +bearer=0.c224.ce15.ce1.dab&time=1319202059 ~~~~ ##### Response @@ -1728,7 +1728,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer jkndsfai1324j0fasdkffdsoijgqwer↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -station=0.c224.ce15.ce1.dab&time=1319202060 +bearer=0.c224.ce15.ce1.dab&time=1319202060 ~~~~ ##### Response From f3f30fe17d5145a908e56574524f45c977c3cedf Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 14:09:45 +0100 Subject: [PATCH 10/19] Add optional 'time_source' parameter There are some concerns about how reliable the time attribute will be from differing clients with differing "clock" sources. It will be difficult to tackle this within the timescales to deliver a finalised 1.0 specification, so as a compromise and to aide future investigation, we have added an optional 'time_source' attribute which allows a client to inform the broadcaster of where they sourced the time from. This will allow a broadcaster to make a better decision about how reliable that time might be and therefore potenitally vary their response to the incoming tag to increase or decreate the range/scope of returned events. --- src/radiotag-api-proposal-v1.00d6.md | 49 ++++++++++++++++++---------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index abf4e06..3266f3a 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -35,6 +35,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - Added recommendation for TLS (HTTPS) - Moved all endpoints in to RadioDNS-standardised path - Changed references from 'station' to 'radio service' or 'bearer' + - Add optional 'time_source' parameter ### URL @@ -126,6 +127,10 @@ A tag *request* specifies a time and bearer. The time is specified using seconds since Jan 1 1970, i.e. the Unix epoch. The bearer is specified using the bearerURI format defined in ETSI TS 103 270. +An optional attribute for the time's source is defined, which allows the +broadcaster to make a more informed decision on the accuracy of the time value +supplied and therefore the event that this request is in relation to. + How that information is interpreted is up to the broadcaster. ### Tag responses @@ -336,12 +341,22 @@ Authorization Not set OR client token OR user token ##### Parameters -------------------------------------------------------------------------------- -Name Value ------- ------------------------------------------------------------------------ -bearer RadioDNS broadcast parameters joined with dots, e.g. - "0.c224.ce15.ce1.dab" +Name Value +----------- ------------------------------------------------------------------- +bearer RadioDNS broadcast parameters joined with dots, e.g. + "0.c224.ce15.ce1.dab" + +time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) + +time_source (Optional) where the time is sourced from, value of either: + + `user` the user has set the client clock manually, + `broadcast` derived from the bearer's time source (e.g. RDS for FM, + the FIG in DAB), + `ntp` derived from IP source -time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) + When not set it is assumed the time is derived from the bearer's + time source. -------------------------------------------------------------------------------- @@ -392,7 +407,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312301004 +bearer=0.c224.ce15.ce1.dab&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -416,7 +431,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312301004 +bearer=0.c224.ce15.ce1.dab&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -469,7 +484,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312302129 +bearer=0.c224.ce15.ce1.dab&time=1312302129&time_source=broadcast ~~~~ ##### Response @@ -519,7 +534,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312195118 +bearer=0.c224.ce15.ce1.dab&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -567,7 +582,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312195118 +bearer=0.c224.ce15.ce1.dab&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -920,7 +935,7 @@ Host: radiotag.bbc.co.uk↵ Authorization:↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1028,7 +1043,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1155,7 +1170,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1340,7 +1355,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201990 +bearer=0.c224.ce15.ce1.dab&time=1319201990&time_source=broadcast ~~~~ ##### Response @@ -1476,7 +1491,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989 +bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1560,7 +1575,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319202059 +bearer=0.c224.ce15.ce1.dab&time=1319202059&time_source=broadcast ~~~~ ##### Response @@ -1728,7 +1743,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer jkndsfai1324j0fasdkffdsoijgqwer↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319202060 +bearer=0.c224.ce15.ce1.dab&time=1319202060&time_source=broadcast ~~~~ ##### Response From c20d2468c584d02a7fbd25008970c53b5a83162c Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 14:28:38 +0100 Subject: [PATCH 11/19] Change RadioDNS domain params format to bearerURI The use of a RadioDNS FQDN format (without the .radiodns.org ending) to define a service is unusual in the wider scope of RadioDNS applications. Changed to the ETSI Hybrid Radio spec-defined bearerURI, which is intended to be a universal identifier for Bearers. --- src/radiotag-api-proposal-v1.00d6.md | 67 ++++++++++++++-------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 3266f3a..4e56e77 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -36,6 +36,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - Moved all endpoints in to RadioDNS-standardised path - Changed references from 'station' to 'radio service' or 'bearer' - Add optional 'time_source' parameter + - Change RadioDNS domain params format to bearerURI ### URL @@ -343,8 +344,8 @@ Authorization Not set OR client token OR user token -------------------------------------------------------------------------------- Name Value ----------- ------------------------------------------------------------------- -bearer RadioDNS broadcast parameters joined with dots, e.g. - "0.c224.ce15.ce1.dab" +bearer RadioDNS bearerURI as defined in ETSI TS 103 270, e.g. + "dab:ce1.ce15.c224.0" time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) @@ -407,7 +408,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312301004&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -431,7 +432,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312301004&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -458,7 +459,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -484,7 +485,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312302129&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1312302129&time_source=broadcast ~~~~ ##### Response @@ -510,7 +511,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -534,7 +535,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312195118&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -561,7 +562,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Meet David Sedaris - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -582,7 +583,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1312195118&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -608,7 +609,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Meet David Sedaris - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -707,7 +708,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -805,7 +806,7 @@ The example below shows these elements in context: 1 Meet David Sedaris - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -836,7 +837,7 @@ The example below shows these elements in context: 3 PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -847,7 +848,7 @@ The example below shows these elements in context: PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -858,7 +859,7 @@ The example below shows these elements in context: PM - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -935,7 +936,7 @@ Host: radiotag.bbc.co.uk↵ Authorization:↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1043,7 +1044,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1079,7 +1080,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1144,7 +1145,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1170,7 +1171,7 @@ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1203,7 +1204,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1355,7 +1356,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201990&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319201990&time_source=broadcast ~~~~ ##### Response @@ -1381,7 +1382,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1432,7 +1433,7 @@ Content-Type: application/xml;charset=utf-8↵ 3 Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1443,7 +1444,7 @@ Content-Type: application/xml;charset=utf-8↵ Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1454,7 +1455,7 @@ Content-Type: application/xml;charset=utf-8↵ Feedback - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1491,7 +1492,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319201989&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1526,7 +1527,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1575,7 +1576,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319202059&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319202059&time_source=broadcast ~~~~ ##### Response @@ -1605,7 +1606,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 @@ -1743,7 +1744,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer jkndsfai1324j0fasdkffdsoijgqwer↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=0.c224.ce15.ce1.dab&time=1319202060&time_source=broadcast +bearer=dab:ce1.ce15.c224.0&time=1319202060&time_source=broadcast ~~~~ ##### Response @@ -1773,7 +1774,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - 0.c224.ce15.ce1.dab + dab:ce1.ce15.c224.0 BBC Radio 4 From 6870b548f68a55545615b368f4b4f7e268774729 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 15:03:58 +0100 Subject: [PATCH 12/19] Added missing version attribute to CPA WWW-Authenticate header --- src/radiotag-api-proposal-v1.00d6.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 4e56e77..288f870 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -416,7 +416,7 @@ bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Tue, 02 Aug 2011 16:03:24 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ Content-Type: text/html;charset=utf-8↵ ↵ Must request client token @@ -440,7 +440,7 @@ bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Tue, 02 Aug 2011 16:03:25 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -543,7 +543,7 @@ bearer=dab:ce1.ce15.c224.0&time=1312195118&time_source=broadcast ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Mon, 01 Aug 2011 10:38:38 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -689,7 +689,7 @@ HTTP Status Code HTTP Status Explanation ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Tue, 02 Aug 2011 16:22:08 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -956,7 +956,7 @@ supported by this auth provider. ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="client"↵ Content-Type: text/html;charset=utf-8↵ ↵ Must request client token @@ -1061,7 +1061,7 @@ programme is shown below: ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -1126,7 +1126,7 @@ for this device. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -1185,7 +1185,7 @@ register. ~~~~ {.example} HTTP/1.1 201 Created↵ Date: Fri, 21 Oct 2011 12:59:49 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -1508,7 +1508,7 @@ to accept the result or upgrade from client to user mode. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 13:00:59 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ @@ -1561,7 +1561,7 @@ stored on the server. ~~~~ {.example} HTTP/1.1 401 Unauthorized↵ Date: Fri, 21 Oct 2011 13:00:59 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: text/html;charset=utf-8↵ ↵ Must request user token @@ -1587,7 +1587,7 @@ request is 200. ~~~~ {.example} HTTP/1.1 200 OK↵ Date: Fri, 21 Oct 2011 13:01:00 GMT↵ -WWW-Authenticate: CPA name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ +WWW-Authenticate: CPA version="1.0" name="BBC AP" uri="https://ap.bbc.co.uk" modes="user"↵ Content-Type: application/xml;charset=utf-8↵ ↵ From 5c447075bc338e6826dddbe1e91a9e86242f83fd Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 15:32:38 +0100 Subject: [PATCH 13/19] Update CPA references --- src/radiotag-api-proposal-v1.00d6.md | 71 ++++++++++++++-------------- 1 file changed, 35 insertions(+), 36 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 288f870..6908ea6 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -429,7 +429,7 @@ Must request client token ~~~~ {.example} POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast @@ -664,7 +664,7 @@ specification](http://www.oclc.org/developer/platform/query-responses). ~~~~ {.example} GET /radiodns/tag/1/tags HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ ↵ ~~~~ @@ -969,7 +969,7 @@ As per the CPA specification, the client begins a client mode registration. Because it has no client identifiers, it must first request these. ~~~~ {.example} -POST /radiodns/tag/1/register HTTP/1.1↵ +POST /register HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-Type: application/json↵ ↵ @@ -1000,15 +1000,15 @@ Now that an identifier and secret have been obtained for the client, these can be exchanged for a client token. ~~~~ {.example} -POST /radiodns/tag/1/token HTTP/1.1↵ +POST /token HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-type: application/x-www-form-urlencoded↵ ↵ { - "grant_type": "authorization_code" + "grant_type": "http://tech.ebu.ch/cpa/1.0/client_credentials", "client_id": "1234", "client_secret": "sdalfqealskdfnk13984r2n23klndvs", - "scope": "radiotag.bbc.co.uk" + "domain": "radiotag.bbc.co.uk" } ~~~~ @@ -1024,11 +1024,9 @@ Cache-control: no-store↵ Pragma: no-cache↵ ↵ { - "description": "RadioTAG token for user Alice", - "short_description": "Alice", - "token": "alsdkfmasdfn1j23nsfjn1", + "access_token": "28b8caec68ae4a8c89dffaa37d131295", "token_type": "bearer", - "scope": "radiotag.bbc.co.uk" + "domain_name": "BBC" } ~~~~ @@ -1040,7 +1038,7 @@ of a POST request to `/tag`. ~~~~ {.example} POST /radiodns/tag/1/tag HTTP/1.1↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ @@ -1113,7 +1111,7 @@ of tags by making a GET request to `/tags` with the token in the header: ~~~~ {.example} GET /radiodns/tag/1/tags HTTP/1.1↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Host: radiotag.bbc.co.uk↵ ↵ ~~~~ @@ -1167,7 +1165,7 @@ the `Tag` button as before. ~~~~ {.example} POST /radiodns/tag/1/tag HTTP/1.1↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ @@ -1233,7 +1231,7 @@ Host: ap.bbc.co.uk↵ { "client_id": "1234", "client_secret": "sdalfqealskdfnk13984r2n23klndvs", - "scope": "radiotag.bbc.co.uk" + "domain": "radiotag.bbc.co.uk" } ~~~~ @@ -1250,10 +1248,11 @@ Cache-Control: no-store↵ Pragma: no-cache↵ ↵ { - "user_code": "Abf13", - "verification_uri": "https://www.bbc.co.uk/id/device", - "expires_in": 1800, - "interval": 5 + "device_code": "197bf88c-749a-42e2-93f0-e206bac2252f", + "user_code": "AbfZDgJr", + "verification_uri": "https://ap.example.com/verify", + "interval": 5, + "expires_in": 1800 } ~~~~ @@ -1287,15 +1286,16 @@ Polling should be attempted for no longer than the `expires_in` duration. ##### Request ~~~~ {.example} -POST /radiodns/tag/1/token HTTP/1.1↵ +POST /token HTTP/1.1↵ Host: ap.bbc.co.uk↵ Content-type: application/json↵ ↵ { - "grant_type": "authorization_code", + "grant_type": "http://tech.ebu.ch/cpa/1.0/device_code", + "device_code": "197bf88c-749a-42e2-93f0-e206bac2252f", "client_id": "1234", - "client_secret": "jkndsfai1324j0fasdkffdsoijgqwer", - "scope": "radiotag.bbc.co.uk" + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "domain": "radiotag.bbc.co.uk" } ~~~~ @@ -1333,11 +1333,10 @@ Cache-control: no-store↵ Pragma: no-cache↵ ↵ { - "description": "RadioTAG token for user Alice", - "short_description": "Alice", - "token": "alsdkfmasdfn1j23nsfjn1", + "user_name": "Alice", + "access_token": "28b8caec68ae4a8c89dffaa37d131295", "token_type": "bearer", - "scope": "radiotag.bbc.co.uk" + "domain_name": "BBC" } ~~~~ @@ -1353,7 +1352,7 @@ stored against the user's account. ~~~~ {.example} POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ bearer=dab:ce1.ce15.c224.0&time=1319201990&time_source=broadcast @@ -1406,7 +1405,7 @@ above are returned in the Atom feed. ~~~~ {.example} GET /radiodns/tag/1/tags HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ -Authorization: Bearer alsdkfmasdfn1j23nsfjn1↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ ↵ ~~~~ @@ -1706,10 +1705,11 @@ Host: ap.bbc.co.uk↵ Content-type: application/x-www-form-urlencoded↵ ↵ { - "grant_type": "authorization_code", + "grant_type": "http://tech.ebu.ch/cpa/1.0/device_code", + "device_code": "197bf88c-749a-42e2-93f0-e206bac2252f", "client_id": "1234", - "device_code": "jkndsfai1324j0fasdkffdsoijgqwer", - "scope": "radiotag.bbc.co.uk" + "client_secret": "sdalfqealskdfnk13984r2n23klndvs", + "domain": "radiotag.bbc.co.uk" } ~~~~ @@ -1723,11 +1723,10 @@ Cache-control: no-store↵ Pragma: no-cache↵ ↵ { - "description": "RadioTAG token for user Alice", - "short_name": "Alice", - "token": "alsdkfmasdfn1j23nsfjn1", + "user_name": "Alice", + "token": "28b8caec68ae4a8c89dffaa37d131295", "token_type": "bearer", - "scope": "radiotag.bbc.co.uk" + "domain_name": "BBC" } ~~~~ @@ -1741,7 +1740,7 @@ acquired `Authorization` header token value: ~~~~ {.example} POST /tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ -Authorization: Bearer jkndsfai1324j0fasdkffdsoijgqwer↵ +Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ bearer=dab:ce1.ce15.c224.0&time=1319202060&time_source=broadcast From 3ed2d0090b9f7593a52ab28522fd241682892d41 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 16:19:15 +0100 Subject: [PATCH 14/19] Fixed URL encoding of bearerURI --- src/radiotag-api-proposal-v1.00d6.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 6908ea6..4d39d91 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -408,7 +408,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -432,7 +432,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1312301004&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1312301004&time_source=broadcast ~~~~ ##### Response @@ -485,7 +485,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer kldhvkjxhoiqwyeh3khkj3↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1312302129&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1312302129&time_source=broadcast ~~~~ ##### Response @@ -511,7 +511,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - dab:ce1.ce15.c224.0 + dab%3Ace1.ce15.c224.0 BBC Radio 4 @@ -535,7 +535,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1312195118&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -583,7 +583,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1312195118&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1312195118&time_source=broadcast ~~~~ ##### Response @@ -936,7 +936,7 @@ Host: radiotag.bbc.co.uk↵ Authorization:↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1042,7 +1042,7 @@ Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1169,7 +1169,7 @@ Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ Host: radiotag.bbc.co.uk↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1355,7 +1355,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319201990&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319201990&time_source=broadcast ~~~~ ##### Response @@ -1491,7 +1491,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319201989&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319201989&time_source=broadcast ~~~~ ##### Response @@ -1575,7 +1575,7 @@ POST /radiodns/tag/1/tag HTTP/1.1↵ Host: radiotag.bbc.co.uk↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319202059&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319202059&time_source=broadcast ~~~~ ##### Response @@ -1743,7 +1743,7 @@ Host: radiotag.bbc.co.uk↵ Authorization: Bearer 28b8caec68ae4a8c89dffaa37d131295↵ Content-Type: application/x-www-form-urlencoded↵ ↵ -bearer=dab:ce1.ce15.c224.0&time=1319202060&time_source=broadcast +bearer=dab%3Ace1.ce15.c224.0&time=1319202060&time_source=broadcast ~~~~ ##### Response From 7965329deecf9ba7119cce71ec4be61c88dd069b Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Mon, 1 Jun 2015 16:20:13 +0100 Subject: [PATCH 15/19] Fixed formatting error in table --- src/radiotag-api-proposal-v1.00d6.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 4d39d91..5903643 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -350,12 +350,10 @@ bearer RadioDNS bearerURI as defined in ETSI TS 103 270, e.g. time Whole number of seconds since 00:00a.m Jan 1 1970 UTC (Unix Epoch) time_source (Optional) where the time is sourced from, value of either: - `user` the user has set the client clock manually, `broadcast` derived from the bearer's time source (e.g. RDS for FM, the FIG in DAB), - `ntp` derived from IP source - + `ntp` derived from IP source. When not set it is assumed the time is derived from the bearer's time source. From 91b3151be8dce9a7817c46b3fc1156b884e0fd1d Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 3 Jun 2015 10:13:37 +0100 Subject: [PATCH 16/19] Replace radiotag:sid and :service with simplified combined element, using bearerURI format. Term sid was incorrect. Changing sid to bearer leaves us with 2x elements representing a service and it's relevant "location", therefore merging in to a single element with text body as the display name and attribute 'uri' with the bearer URI. --- src/radiotag-api-proposal-v1.00d6.md | 81 +++++++++++----------------- 1 file changed, 32 insertions(+), 49 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 5903643..39df2a1 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -37,6 +37,8 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - Changed references from 'station' to 'radio service' or 'bearer' - Add optional 'time_source' parameter - Change RadioDNS domain params format to bearerURI + - Replace radiotag:sid and :service with simplified combined element, using + bearerURI format. ### URL @@ -457,8 +459,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:fb669d2c-63b3-420b-9dd6-131f5d58e68a @@ -509,8 +510,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - dab%3Ace1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97 @@ -560,8 +560,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Meet David Sedaris - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 @@ -607,8 +606,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Meet David Sedaris - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 @@ -706,8 +704,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 PM - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d @@ -751,24 +748,24 @@ All dates are UTC in ISO format ([ISO The RadioTAG specification also requires the following: ------------------------------------------------------------------------------ -Element Description Max length ----------------- ----------------------------------------------- ---------- -author name of tag service provider (e.g. BBC, Global) 16 +--------------------------------------------------------------------------------- +Element Description Max length +---------------- ----------------------------------------------- ---------- +author name of tag service provider (e.g. BBC, Global) 16 -published the datetime of creation (= tag time) 20 +published the datetime of creation (= tag time) 20 -summary text only - i.e. must not include HTML tags 180 +summary text only - i.e. must not include HTML tags 180 -link rel="image" link to 100x100 image representing the tag 255 +link rel="image" link to 100x100 image representing the tag 255 -link rel="self" a user accessible url for the tag 255 +link rel="self" a user accessible url for the tag 255 -radiotag:service the human-readable name of the service tagged 16 +radiotag:service the human-readable name of the service tagged 16 -radiotag:sid RadioDNS service identifier 32 +radiotag:service uri the radio service's bearer URI 32 ------------------------------------------------------------------------------ +--------------------------------------------------------------------------------- Note the difference here between `id` and `link rel="self"`. `id` is a globally unique identifier. `link rel="self"` gives the url as visible @@ -804,8 +801,7 @@ The example below shows these elements in context: 1 Meet David Sedaris - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:5001c814-7a28-42a4-b35a-eef17abc7249 @@ -835,8 +831,7 @@ The example below shows these elements in context: 3 PM - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:8facc0c0-ce13-4349-8664-dc71d55c6c97 @@ -846,8 +841,7 @@ The example below shows these elements in context: PM - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:9f61f2c1-f3f7-4ff7-bc61-32f0e468054d @@ -857,8 +851,7 @@ The example below shows these elements in context: PM - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:8e67aef6-4e8c-47ac-bc10-f89d4d5bac17 @@ -1076,8 +1069,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 @@ -1141,8 +1133,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 @@ -1200,8 +1191,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:4b8a1b72-f76b-4dc2-9db8-cb15042454ea @@ -1379,8 +1369,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:5967db0e-dc63-428d-a075-90cf316ded5d @@ -1430,8 +1419,7 @@ Content-Type: application/xml;charset=utf-8↵ 3 Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:5967db0e-dc63-428d-a075-90cf316ded5d @@ -1441,8 +1429,7 @@ Content-Type: application/xml;charset=utf-8↵ Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:4b8a1b72-f76b-4dc2-9db8-cb15042454ea @@ -1452,8 +1439,7 @@ Content-Type: application/xml;charset=utf-8↵ Feedback - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:661417da-cb8d-4fd0-a8fd-9b55ed2086d7 @@ -1524,8 +1510,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:3bfaa9dd-11ed-45f9-8f3c-6587db086b04 @@ -1603,8 +1588,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:8ea43558-70c2-4a4a-aeb9-8ffeee700898 @@ -1771,8 +1755,7 @@ Content-Type: application/xml;charset=utf-8↵ 1 The Archers - dab:ce1.ce15.c224.0 - BBC Radio 4 + BBC Radio 4 urn:uuid:fcbb6008-aa54-45b4-91c9-78ec0655f9d7 From 28163370a046bf0adf260bf4966682e8332bb718 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 3 Jun 2015 11:47:47 +0100 Subject: [PATCH 17/19] Remove unnecessary limitation definitions --- src/radiotag-api-proposal-v1.00d6.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 39df2a1..2a0cb24 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -866,27 +866,25 @@ The example below shows these elements in context: ### Data elements ----------------------------------------------------------------------------------------------- -Data element Max. size in bytes Notes ----------------- ------------------ -------------------------------------------------------- -author 16 Atom entry +------------------------------------------------------------------------------------------ +Data element Max. size in bytes Notes +------------ ------------------ -------------------------------------------------------- +author 16 Atom entry -id 48 Atom entry +id 48 Atom entry -pin number 10 +pin number 10 -service id (sid) 32 As specified by RadioDNS +bearerURI 32 As specified by RadioDNS -summary 180 Atom entry +summary 180 Atom entry -title 128 Atom entry (compatible with DAB/RDS Livetext) +title 128 Atom entry (compatible with DAB/RDS Livetext) -token 48 +url 255 See [RFC 2616 Section + 3.2.1](http://tools.ietf.org/html/rfc2616#section-3.2.1) -url 255 See [RFC 2616 Section - 3.2.1](http://tools.ietf.org/html/rfc2616#section-3.2.1) - ----------------------------------------------------------------------------------------------- +------------------------------------------------------------------------------------------ # Appendix From b3eaba8e4d939e9df422baa39abd7c89427808d3 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 3 Jun 2015 12:10:14 +0100 Subject: [PATCH 18/19] Remove 100x100 image size restriction The RadioTAG specification should not be involved in the specification of display restrictions. The 100x100 restriction was placed in the spec due to the targeting of a specific device. Since inclusion, display technologies have improved significantly to the point that 100x100 may look poor on modern displays. --- src/radiotag-api-proposal-v1.00d6.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 2a0cb24..1321507 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -38,7 +38,8 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - Add optional 'time_source' parameter - Change RadioDNS domain params format to bearerURI - Replace radiotag:sid and :service with simplified combined element, using - bearerURI format. + bearerURI format + - Remove 100x100 image size restriction ### URL @@ -757,7 +758,7 @@ published the datetime of creation (= tag time) 20 summary text only - i.e. must not include HTML tags 180 -link rel="image" link to 100x100 image representing the tag 255 +link rel="image" link to an image representing the tag 255 link rel="self" a user accessible url for the tag 255 From 7e95ffb7bfa265c29823e7dd38f543925a8ff181 Mon Sep 17 00:00:00 2001 From: Andy Buckingham Date: Wed, 3 Jun 2015 15:19:42 +0100 Subject: [PATCH 19/19] Version bump --- src/radiotag-api-proposal-v1.00d6.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/radiotag-api-proposal-v1.00d6.md b/src/radiotag-api-proposal-v1.00d6.md index 1321507..5d86860 100644 --- a/src/radiotag-api-proposal-v1.00d6.md +++ b/src/radiotag-api-proposal-v1.00d6.md @@ -1,6 +1,6 @@ % RadioTAG 1.00 specification, draft 6 % Sean O'Halpin (BBC R&D); Chris Lowis (BBC R&D) -% 2015-06- +% 2015-06-03 ## Front matter ### Authors @@ -26,7 +26,7 @@ Andy Buckingham (togglebit), Robin Cooksey (Frontier Silicon) - 'paired' changed to 'user (identity)' - 'client' changed to 'receiver' - 'can_register' changed to 'identity' -- Draft 6: 2015-06- +- Draft 6: 2015-06-03 - Updated terminology to reflect CPA terms - Replaced Tag auth procedure with draft CPA procedure - Updated and simplified req/rep examples, ensured compliance with latest