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

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 01:07:11 UTC