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

hello annette.

On 2015-07-29 1:08 , Annette Greiner wrote:
> Weighing all the arguments, I feel like I understand the reasoning behind avoiding versioning, that it shouldn't be needed if you only ever change what's under the hood and leave the actual interface alone, but I do wonder how successful people have been in getting the interface part right the first time, or at least right enough that any revision could really be considered a different API.

i don't want to get into any REST preaching here, but one of the main 
pillars of REST is that the interface is uniform, i.e. there is no need 
for people to even invent interfaces, and thus there is no need to 
version them. the only thing that does need service-specific definition 
(maybe) is the media type, which thus may be what you actually refer to 
when you say "interface" above. HTTP hasn't changed in a very long time 
(even though there are additions that people define if they want to 
expose additional info in that interface).

this gets web architecture to the point that what services operate on 
are media types. and that's what i was talking about originally. 
well-designed media types should be open and extensible, so that they 
can carry basic data as well as additional one. very often, this is done 
robustly defining "must ignore" semantics in the processing model. some 
media types have attempted to use or allow "must understand" semantics 
(SOAP is one well-known example), but this can cause a lot of breakage 
because lazy service providers not wanting to think about backwards 
compatibility then label everything as "must understand", effectively 
creating a new service that's not generally consumable anymore.

> I guess I don't see a big advantage to putting that "new API" at http://otherthing.mydata.org instead of http://thing.mydata.org/v2. As long as you keep both versions up and running, you don't break anyone's code.

how you name the services is completely irrelevant, and i would strongly 
suggest for the DWBP document not to create the impression that the 
above two URIs are different in any way (other than maybe following some 
kind of friendly naming convention that has no technical implication 
whatsoever).

the huge problem is that you create split personality resources. if you 
serve the same resource at two URIs, what is the resource's "actual" 
URI? or does he same resource now have two identities? that would be 
very bad because now everybody working with those resource identities 
has to know about both of them. so one giant anti-pattern is to create 
these kind of "duplicate identities", which create big headaches in the 
long run when users count and depend on unique and robust identifiers.

> Using a version number at least helps clarify what is different.

but what *is* different? are these really two resources now? if they 
are, there's no need to relate them at all. if they have a well-defined 
relationship, that should be made very explicit by relating them in a 
way that is discoverable and stable.

experience shows that while it may seem like no big deal to assign these 
additional identifiers, it wreaks havoc on one of the main pillars of 
REST, i.e. unique and stable resource identifiers.

> As a developer, I think it's much easier to decide to use "v2" in a new client than to decide whether to use "thing" or "otherthing".

again, the name is completely irrelevant. and most importantly, 
providers should really really try to avoid minting more than one URI 
for resources, it makes consumption (and more importantly, processing 
and relating resources robustly) much harder.

> I find the example of HTML unhelpful, because what gives a web site its resilience to unheralded change is the human in the loop. Where we attempt to navigate web sites in code (scraping, bookmarking), things get brittle fast.

no, what makes web sites so stable actually *is* the design of HTML that 
allows production and consumption across a vast variety of different 
"versions" of the language. that's why HTML does *not* need a version 
identifier in the URI or in the media type. you can mix and match 
versions and things Just Work. they Just Work because of the processing 
model (must ignore on unknown elements/attributes, plus the requirement 
to process content of unknown elements), which means that responsible 
providers can create HTML that is consumable by software that has been 
created over the course of two decades. that's nothing to sneeze upon.

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 Friday, 31 July 2015 18:03:09 UTC