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

You misunderstand me. When I talk about the vocabulary here, I’m not talking about the URIs themselves. I’m talking about the affordances in each response that define the relationships between the links, like the rel tags. I recognize that strict REST demands that the client discover the URIs on the fly. When I talk about hops in this context, I’m talking about the exploratory path that the client follows when following the links, not the path represented by a URI.

It seems to me one would want to keep consistent URIs for product resources, since that fits with the idea of unique and stable identifiers. That seems to go against the idea that URIs should be completely changeable, but perhaps that is an exception that “goes without saying”.
-Annette
--
Annette Greiner
NERSC Data and Analytics Services
Lawrence Berkeley National Laboratory
510-495-2935

On Aug 4, 2015, at 9:59 AM, Erik Wilde <dret@berkeley.edu> wrote:

> 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 Wednesday, 5 August 2015 19:40:51 UTC