[CALL] Align RadioTAG URL structure with those of other applications

[Andy Buckingham]

At present the endpoints in the RadioTAG Draft 5 specification are all on the route of the identified RadioTAG host, e.g.:

  http://host/tag

  http://host/token

Other RadioDNS-related specifications such as RadioEPG and RadioVIS adopt a common format for endpoint URLs:

  http://<host>/radiodns/<app>/<resource>

  

It is proposed we should move the URLs to the same format, for example the tag endpoint URL would become:

  http://<host>/radiodns/tag/tag

General consensus on the call appeared to be positive regarding this change, but I'd appreciate any feedback for or against this change.

[Robin Cooksey]

Hi Andy,

 

This sounds like a very sensible change, that will give RadioTAG more consistency with the other applications.

 

One observation is that as the app and primary resource name are the same, this results the URL ending “/tag/tag”, which looks a bit odd.

I guess this isn’t very different to the RadioVIS HTTP case (vis/vis.json), and is only really trivial and cosmetic anyway – but I wondered if it’s worth considering changing the name of the resources to something other than tag.

Given that the scope of the application is made clear (with the “tag” in the <app> part), the resource could be more named after the operation – e.g. something like “submit”, or “create”, and something like “get” instead of tags.

E.g. http://<host>/radiodns/tag/create

And http://<host>/radiodns/tag/get

 

Any thoughts?

 

Best regards,

Robin

 

 

--
You received this message because you are subscribed to the Google Groups "RadioTAG developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to radiotag-develo...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Andy Buckingham (RadioDNS)]

I agree that we should try and minimise confusion with these names.
That does make me wonder if we should use 'get' due to its similarity
to the HTTP method name GET. Could I propose we use:

/radiodns/tag/create
/radiodns/tag/list

Both descriptive and, with the added context from the app ('tag'),
fairly self explanatory.

[Robin Cooksey]

Hi Andy,

Good point - your suggestions for create and list look good to me.

What about the other end-points that are currently defined the spec? (e.g. token, registration_key and register). I guess these are probably still sensible names under the new structure?

Best regards,
Robin

> -----Original Message-----
> From: radiotag-...@googlegroups.com [mailto:radiotag-
> devel...@googlegroups.com] On Behalf Of Andy Buckingham (RadioDNS)
> Sent: 29 June 2013 11:46
> To: RadioTAG Application Team
> Subject: Re: [CALL] Align RadioTAG URL structure with those of other
> applications
>

> I agree that we should try and minimise confusion with these names.
> That does make me wonder if we should use 'get' due to its similarity to the
> HTTP method name GET. Could I propose we use:
>
> /radiodns/tag/create
> /radiodns/tag/list
>
> Both descriptive and, with the added context from the app ('tag'), fairly self
> explanatory.
>
>

> On 28 June 2013 16:42, Robin Cooksey <Robin.Cooksey@frontier-

> silicon.com> wrote:
> > Hi Andy,
> >
> >
> >
> > This sounds like a very sensible change, that will give RadioTAG more
> > consistency with the other applications.
> >
> >
> >
> > One observation is that as the app and primary resource name are the
> > same, this results the URL ending "/tag/tag", which looks a bit odd.
> >
> > I guess this isn't very different to the RadioVIS HTTP case

> > (vis/vis.json), and is only really trivial and cosmetic anyway - but I

> > wondered if it's worth considering changing the name of the resources
> > to something other than tag.
> >
> > Given that the scope of the application is made clear (with the "tag"
> > in the <app> part), the resource could be more named after the operation

> - e.g.

[Andy Buckingham]

They make sense to me.

Should we receive a lack of sustained objection to the proposal to split the auth model from RadioTAG, these endpoint names should be reconsidered in their new scope.

A

> > an email to radiotag-developers+unsub...@googlegroups.com.

> > For more options, visit https://groups.google.com/groups/opt_out.
> >
> >
> >
> > --
> > You received this message because you are subscribed to the Google
> > Groups "RadioTAG developers" group.
> > To unsubscribe from this group and stop receiving emails from it, send

> > an email to radiotag-developers+unsub...@googlegroups.com.

> > For more options, visit https://groups.google.com/groups/opt_out.
> >
> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "RadioTAG developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to radiotag-developers+unsub...@googlegroups.com.

[Ben Husmann]

I agree with the proposed approach and like the format you've suggested.

/radiodns/tag/create 
/radiodns/tag/list 

[Chris Lowis]

Hi,

I think the reason we chose these names is to adhere to (pretty common today) REST-like[1] principles. That is "tag" is a resource, and you POST to the endpoint to create a new one, or PUT (with an id) to modify. To receive a list of resources you GET the resource root (/tags). The plural/singular convention is one that Ruby on Rails adopts, which I think is where we took inspiration.

I think switching to a GET request to /tag/create would be unusual, and is likely to cause confusion. I suspect that implementations of TAG are likely to be made without reference to the VIS spec, so I don't see the need for consistency here.

I'd recommend keeping the URLs as per [2]

Cheers,

Chris

[1] http://en.wikipedia.org/wiki/Representational_state_transfer
[2] http://radiotag.prototyping.bbc.co.uk/docs/radiotag-api-proposal-v1.00.html#sec-6-1



____________________________________
____
From: radiotag-...@googlegroups.com [radiotag-...@googlegroups.com] on behalf of Andy Buckingham (RadioDNS) [andy.bu...@radiodns.org]
Sent: 29 June 2013 11:45
To: RadioTAG Application Team
Subject: Re: [CALL] Align RadioTAG URL structure with those of other applications

-----------------------------
http://www.bbc.co.uk
This e-mail (and any attachments) is confidential and
may contain personal views which are not the views of the BBC unless specifically stated.
If you have received it in
error, please delete it from your system.
Do not use, copy or disclose the
information in any way nor act in reliance on it and notify the sender
immediately.
Please note that the BBC monitors e-mails
sent or received.
Further communication will signify your consent to
this.
-----------------------------

[Andy Buckingham]

Thanks Chris. I must confess, I had forgotten about the REST-ful like considerations for the original endpoint names.

With regard to putting the endpoints within their own namespace on the server (e.g. /radiodns/tag/), the reason this was adopted in other RadioDNS specifications was to reduce barriers of entry for smaller operators.

We explicitly define URLs (behind host resolution) to simplify the spec rather than allowing a way of discovering the specific URLs for tag, listing tags etc. One thing we saw with VIS and EPG were small operators running all of their RadioDNS apps off their same web site server instance. For example, imagine the station hot100.com, they may have the following endpoints:

hot100.com/vis.json

hot100.com/XSI.xml

hot100.com/tag

hot100.com/tags

As long as the specs don't clash in names, this is still theoretically possible, but we also run the risk of clashing with another resource on the servers public root. The view was taken to minimise collision risk and to cleanse the public root of those who wish to bundle multiple services on a single box by putting them in to /radiodns/<app>/

How does everyone feel about adopting this design in to Tag?

If we did move to the /radiodns/tag/ namespace, should we retain the REST-ful names or avoid the repetition in the endpoint names?

> email to radiotag-developers+unsub...@googlegroups.com.

> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "RadioTAG developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to radiotag-developers+unsub...@googlegroups.com.

> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
You received this message because you are subscribed to the Google Groups "RadioTAG developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to radiotag-developers+unsub...@googlegroups.com.

[James Harrison]

On 03/07/13 07:34, Andy Buckingham wrote:
> How does everyone feel about adopting this design in to Tag?
> If we did move to the /radiodns/tag/ namespace, should we retain the
> REST-ful names or avoid the repetition in the endpoint names?
>
>

Certainly this makes a lot of sense to me, both in terms of consistency
with other RadioDNS specifications and in terms of avoiding namespace
collisions with existing applications on shared domains.

The current set of RESTful interaction endpoints seems fairly clear; I
don't think there's much point in adjusting them unless absolutely required.
--
Cheers,
James Harrison

[Andy Buckingham]

The current set of RESTful interaction endpoints seems fairly clear; I 
don't think there's much point in adjusting them unless absolutely required. 

To clarify, even with the repetition that it would introduce? (e.g. /radiodns/tag/tag and /radiodns/tag/tags ?)

[Andy Buckingham]

To draw this conversation to a conclusion, I'm going to propose the next draft amend the endpoint paths to the following:

/radiodns/tag/tag

/radiodns/tag/tags

Whilst we introduce repetition, when clearly specified this pattern makes sense (e.g. /radiodns/<app>/<endpoint>) and I agree that keeping the naming REST'ful is a worthwhile goal.