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

Erik,
One thing that seems contradictory to me in what I read about REST done right is the idea of building an API so that there is essentially no interface. There’s a URI structure under the hood, and the client figures it out on the fly by following the links. But writing the client software seems really difficult, then. You’d basically have to write a web browser that’s somehow particularly attuned to the data that the API makes available but general enough to work with whatever terminology and structure (what I consider the interface) the maker of the API chose to use. That seems too much to expect a client developer to do. On the other hand, you can say that the developer can work through the API manually and discover the terms and structure for herself, so the client doesn’t really need to be that general. But as soon as we make that leap, the API is no longer immune to versioning issues. Unless the client is written very generally, a small change in the interface will break it. 

Another thing that seems contradictory is the fact that it is problematic to create split-personality resources, and yet Fielding himself says the following [1], which is what my comment about the two possible URIs was a reaction to: 
"It is always possible for some unexpected reason to come along that requires a completely different API, especially when the semantics of the interface change or security issues require the abandonment of previously deployed software. My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system with a new brand.” I think you would agree that that also creates split-personality resources, if what you’re versioning really is the API (the interface). 

My feeling is that one should avoid changing the interface as much as possible, use HATEOAS for its elegance, but version the API for the sake of being developer friendly. I could be talked into dropping the versioning if I found out that the unversioned, learned-on-the-fly approach was successfully being used in practice.
-Annette


[1] http://www.infoq.com/articles/roy-fielding-on-versioning

--
Annette Greiner
NERSC Data and Analytics Services
Lawrence Berkeley National Laboratory
510-495-2935

On Jul 31, 2015, at 11:02 AM, Erik Wilde <dret@berkeley.edu> wrote:

> 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 Tuesday, 4 August 2015 00:31:28 UTC