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

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. Thus, the URIs can change without breaking the client. But changing the vocabulary terms would break any client that isn’t built to do some pretty heavy lifting. 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 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?

Maybe I should be asking for you to recommend a good book on this...
-AG
--
Annette Greiner
NERSC Data and Analytics Services
Lawrence Berkeley National Laboratory
510-495-2935

On Aug 3, 2015, at 6:06 PM, Erik Wilde <dret@berkeley.edu> wrote:

> hello annette.
> 
> thanks a lot for your response!
> 
> On 2015-08-03 17:30 , Annette Greiner wrote:
>> 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.
> 
> maybe we have a terminology issue here. in #RESTland, there is an interface (like any distributed information system needs an interface), but the magic is in the fact that it's uniform, i.e. when you design a service you work with the uniform interface and design your representations so that using the uniform interface, clients can navigate the resources you are providing and interact with them.



> 
> also, you can *extend* the uniform interface in ways that are in line with it, such as by adding new header fields that are not allowed to overwrite or alter the meaning of existing ones, but that may provide additional information that you might want to expose.
> 
> (coincidentally, i just proposed such a thing today for a new header field that services could use to expose the fact that resources have a limited lifespan: https://tools.ietf.org/html/draft-wilde-sunset-header)
> 
> after spending a long time in web and REST land, i always find it confusing (for me) when people separate API and data. in REST, your data *is* your API, or let's say your media type is your API. of course, in web REST, your actual API is HTTP, but that's a given. you may pick and choose from ways how to extend HTTP, but the goal should be to do as little of that as possible.
> 
> then all that remains is to design your representations. we talked about census date earlier. there should be a media type for it, or reuse an existing one and make sure that your specific use of it is made discoverable in the representation. if you want to provide access to multiple census datasets, pick an existing media type for this (Atom, LDP, AS, and probably many more), or design your own if you're unhappy with all of them. again, what you're doing is designing representations so that clients can navigate the web of resources that you are exposing. the API always is the same.
> 
> i have to admit that i never understand why people seem to think that following links is hard to understand. writing REST client software is no harder than in other architectural styles, it just is different because you're following links instead of constructing calls to "HTTP endpoints" (i cannot believe i am actually using this term).
> 
>> 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.
> 
> nobody says REST does wonders. but it allows robust evolution. your representation allows a client to do one thing? include a link and clients can do it following that link. you want to allow newer clients to do something else? add a new link that old clients will not understand and ignore, and new clients can do the new thing. same representation for both clients. if you start omitting the original links then yes, the old clients will not find those anymore and stop working, but that's just your decision to stop being nice to them.
> 
>> 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).
> 
> i tried to say what roy says much better. if you start minting new URIs, stop pretending you have the "same resource but at two URIs". two URIs mean two resources (unless you have a carefully designed and often brittle way how to reliably establish URI equivalence). so instead of pretending you have "two versions of one resource", just be honest and call them two resources, that may have some loose historical connection (that old one is the one we served for a while and the new one is working in a completely different way).
> 
>> 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.
> 
> the API is always the same, at least in REST. you cannot version it and if you do, you loose pretty much all of the value that REST provides.
> 
>> 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.
> 
> any service using JSON-LD satisfies this. and please keep in mind that "unversioned" does not equal "learned-on-the-fly". it simply means that the media type design allows old clients to use new services, and vice versa. the old clients in most cases simply happily ignore all the stuff that was added after they were coded, and that's fine as long as the new representations do not break any of the assumptions that those old clients need to accomplish their application goals.
> 
> 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 03:28:19 UTC