Re: [dwbp] BP - URI structure is not relevant for REST

hello annette.

On 2015-08-03 20:27 , Annette Greiner wrote:
> I think my difficulty is with the idea of a completely uniform interface. As I understand it, in a hypermedia API, you assign labels for the various URIs, so that clients have a consistent vocabulary to follow.

oh no, that's definitely an antipattern. if your API does not work with 
randomized URIs, you have a problem. it is nice to use "speaking" URIs, 
but you shouldn't depend on them, and in fact it is a bit risky to use 
them because client developers are lured into taking shortcuts and 
guessing URIs instead of properly following links.

for our web services at EMC, we had a test server that would randomly 
assign URIs to resources, instead of using the pretty "speaking' ones we 
used in the production server. any client failing to work with the test 
server had some broken code in it hardcoding URI assumptions.

> Thus, the URIs can change without breaking the client.

they can change because clients *only* get URIs by taking them from 
links. they might compose them using URI templates as well, but that's 
something that you rarely see used correctly in practice, so in the end 
most REST APIs boil down to good old "follow-your-nose" principles.

> But changing the vocabulary terms would break any client that isn’t built to do some pretty heavy lifting.

that only happens when you let clients guess URIs, and that's not 
something they should be doing. like i said above, that's one of the big 
anti-patterns in REST.

> When I’ve designed REST-like APIs in the past, there has always been a lot of discussion about what URIs to use (“Do we do /dogs/collars/ or /collars/dogs/?” “No, we should do /canines/restraints"), and I think that setting up a fully REST-compliant one would entail much similar discussion about the vocabulary (“Do we point ‘dogs’ at ‘collars’ or point ‘collars’ at ‘dogs’?). Either way, you define a sort of schema that you hope you will not need to change.

that's why personally, i tend to discourage people from overdesigning 
the URI space. perspectives change, and URIs shouldn't, so if you 
hardcode a perspective into URI paths, you'll end up with structure that 
sometimes looks like a good fit, and sometimes not so much.

what i do recommend is to have URIs for exploration paths (i.e., do have 
/dogs/collars/ as the URI for listing all dog collars), but then use 
vanilla URIs for the actual "product" resources (i.e., a specific dog 
collar is /product/17312765 because it might as well be listed as a cat 
collar as well).

> That would not be an issue if one expected each client to discover the vocabulary and structure on its own, but that’s where it starts seeming like too much work for developers. Am I misinterpreting what’s meant by discovering on the fly? And if URIs are changeable, then how can one have a unique and stable identifier for something several hops down?

the idea of something being "several hops down" is the problem here. 
nothing ever is "several hops down". resources in REST by definition are 
a flat space. every resource has a URI, and all URIs are equal. URI 
paths are nothing but a convenience and i do like well-designed URI 
paths because they make life easier, but if anything in the service or 
consuming clients depends on that structure, your service has a serious 
design flaw (at least in REST-land).

cheers,

dret.

-- 
erik wilde | mailto:dret@berkeley.edu  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

Received on Tuesday, 4 August 2015 17:00:10 UTC