Tuesday, December 12, 2006

REST URI naming convention

Over on the Yahoo SOA list there has been a REST discussion where I've continued to not see the benefits of REST for prime time business development....

But there was also a discussion about URIs and whether they should be opaque (meaningless) or sensibly named. I'd like to make a REST proposal

All URIs in REST must be meaningful, they should clearly articulate the type of resource and its place in the hierarchy, individual resource identification should be done via a GUID. The GUID is used to standardise the use of IDs and to provide a clear identifier of the meaningful and opaque parts of theURI.


Thus
http://www.foo.com/customer/invoice
would be a "good" URI starting point and
http://www.foo.com/customer/invoice/8900183b-fb31-4ee7-a5be-c78ada4b2312
would be an individual resource identifier.
http://www.foo.com/customer
would be the customer starting point and
http://www.foo.com/customer/1cb792d5-a521-4123-b081-5bd07328bca5

would be a specific customer.

To me the lack of agreement on naming conventions to REST is indicative of its prototyping feel. Agreeing that URIs MUST have meaningful names would make it simpler to debug, simpler for developers to understand and will clearly separate roots from resources.

Comments?

Technorati Tags:

8 comments:

Anonymous said...

I say SHOULD, not MUST. The simple fact is that the architecture works fine with meaningless URIs (as witnessed by many websites with crazy formats).

Steve Jones said...

Stu,

Its got to be MUST or nothing, so what if people use dumb names? Why not just say that this is bad practice? To me SHOULD indicates that there are valid reasons to have dumb names. I'm struggling to think of any.

C code works fine with meaningless names, witness the IOCCC :) This doesn't mean that stuff is good C code (its great.. but in a very very bad way!). Same goes for Java, Ada, C#, PHP, Ruby etc, when I review project code I have it as a MUST not as a SHOULD, because there are no excuses I've ever heard that are anything other than laziness.

Having decent names would help maintenance, thus reduce TCO, thus for me its again a MUST.

Anonymous said...

[sorry if you get multiple copies of this - I'm not sure if it's my google sign-in not working or just moderatio n]

My own opinion is that it's a good idea to make HTTP URIs self-explanatory wherever possible, but that the naming must not be considered any more than a hint, for convenience.

I have some questions about your proposal, three in one sentence: "they should clearly articulate the type of resource and its place in the hierarchy, individual resource identification should be done via a GUID"

1. what do you mean by "type of resource"? Ok, URIs can be typed using RDF, but it's hard to express that within the URI itself. The notion of a URI having a type in general seems to be confusing resources and objects as found in OO languages or even files - they're very different things (although anything identifiable can be a resource).

2. the use of a slash-separated path elements articulates the hierarchy in the HTTP scheme (if one is appropriate - often for the benefit of relative addressing), what more do you need?

3. URIs *are* GUIDs - why do you need an arbitrary opaque string on top?

Also - what do you mean by "clearly separate roots from resources" - roots of what? (If you mean the path part, then again that's there in the HTTP URI syntax).

There's an potential architectural problem with global naming conventions over URIs, as Tim Berners-Lee puts it:
[[
The architecture of the web is that the space of identifiers
on an http web site is owned by the owner of the domain name.
The owner, "publisher", is free to allocate identifiers
and define how they are served.

Any variation from this breaks the web.
]]

I assume when you say "All URIs in REST..." it's shorthand for "URIs used with HTTP following the REST architectural style". Given that HTTP was designed with this architectural style (although it wasn't formalised at the time), I don't understand why you have trouble seeing the "benefits of REST for prime time business development". Isn't the Web prime time?

Recommended reading: Chapter 5, WebArch.

Steve Jones said...

The naming should be considered IMO the same way that naming of methods and variables is considered in decent code, namely it should mean something to people reading it.

1) By resource type, I just mean the name of the type of resource, if its an invoice then invoice, a customer then customer, a yield forecast then yieldforecast. Not as complex as RDF just the same as naming conventions in programming.

2) I don't think you need anything else, that is what I was proposing (i.e. customer/invoice, all invoices related to a customer)

3) URIs are GUIDs but the reason for the GUID at the end is to split the start point of the REST process from invocation of a specific resource, so specific resources use a GUID (rather than an invoice ID, Customer ID or the like) just to make it clear that this is an individual instance.

On roots from resources I mean the start point of a REST event, e.g. the bit where you "GET" customer/invoice and it helps you to search for your invoices and returns customer/invoice/GUID for the specific instance.

I don't disagree with TBL but there is also nothing that stops various publishers agreeing on a convention .

And no I don't mean all URIs I mean those that are computer->computer targetted. REST is computer to computer, it is not the same (IMO) as the computer->human or human->human parts of the web.

I don't want to get into the REST != web debate on this thread as I'd like to debate the URI naming thing, but I've read the paper and my comment still stands, remember here I mean system->system interactions not those involving people.

Anonymous said...

I know we've been over this multiple times, but still ... REST itself does not define a convention like this because it doesn't care, similarly to C or C++, who define rules for identifieres, but no convention for naming them.

First of all, I finally found a reference to URI opacity, in the axioms of the Web:

http://www.w3.org/DesignIssues/Axioms#opaque

A very good discussion about URI naming conventions can be found in the REST Wiki, including an opposing view point, at these URIs:

http://rest.blueoxen.net/cgi-bin/wiki.pl?PathsAndQueryStrings

http://rest.blueoxen.net/cgi-bin/wiki.pl?UriFormsAreIrrelevantImho

Steve Jones said...

But Stefan, while the C and C++ specs don't say what a decent name is, pretty much every course and book tells you to use sensible variable, method and class names.

There is nothing in the Java language spec that dictates decent naming, but there is agreement that names in code should have meaning in order to be considered "good" and that rubbish names are "bad".

So what is the big deal with saying that in implemented REST systems the URIs should be well named. Of course the computer doesn't care about the name, but the developer most certainly does.

So no, C, C++, C#, Ada, Java etc do not in the langauge spec say that the name matters... but in implementation you are going to fail your course or code review if they aren't sensible. REST should have the same level of professionalism if the URI is an important resource identifier.

Anonymous said...

Its a very nice blog for...
architects in bangalore , architects in bangalore , interior designers in Bangalore , interior designers in Bangalore , architects in bangalore , architects in bangalore , interior designers in bangalore

Anonymous said...

I hope you are not suggesting this glaring obvious "feature" was just overlooked. Given that, why to you suppose it's not part of REST?

Who determines what's sensible? Czechs? Physicists? Czech physicists? What about systems that consume these services? What is "sensible" to them?

Are these sensible? How does REST know?

/osoba/jméno
/adiabatic/asmptotic/higgs
/i8934/XU8449/Z-WER

Should C# enforce sensible variable names? Seriously, you should be able to convince yourself this is a really bad suggestion in just a few minutes.

Should URIs make sense? Of course! Should REST enforce "sensible" names? You must be joking!