On Feb 11, 2010, at 12:43 AM, Kevin Duffey wrote:
> Hi,
>
> > > if you write clients that rely on any kind of expectation about the representations
> >
> > I don't believe this is realistic. If a client states to the server that it Accepts a certain type he either gets the correct representation or an error
>
> >Yes. But if you code the client with the assumption that certain links will definitely be >present in the response the client is not doing REST. Clients must react on what they >are being sent (react on the state they are being put into by the server) and try to >persue their goal from there.
>
> Wouldn't developers consuming HATEOAS apis have some sort of document that explains each call and the possible uris they can then call? For example, if I were to use an API built around orders, and I POST to create a new order.. I would want to know ahead of time what sort of possible responses would come back
Well, as I said in the long answer to Marc, yes, the client needs to know the set of possible stuff it has to deal with (otherwise you would not have any clue what to code, eh?). But clients should not make any particular assumptions about a response (like the presence of a certain transition). AtomPub for example says that collections are represented as Atom feeds. That violates REST's hypermedia constraint. (see link to thread on atom-protocol).
> so that I could write code to those responses. If I get a response back with URIs to GET, DELETE and PUT, does my code just scan the responses and know what to do? Or do I as the programmer provide some logic for each of those responses. Perhaps I don't want to allow the end user that I building a GUI for, for example, to be able to update or delete, just GET. Maybe I am misunderstanding what you said above, but it sounded like the code itself would utilize all the response URIs and provide them for... say the end user.
We must differentiate between A) 'passive' clients that really only present the application state to some human user or crawlers that just react to whatever they find and B) client that follow some goal and thus have some sort of state machine of their own.
> Now assuming I know ahead of time and write code to handle these URIs, my client wouldn't break if the service evolved by adding a new URI or adding methods for an already provided URI. I am not sure tho if I completely understand what you are implying.
I am saying that the client must not assume anything about the response it receives at design/implementation time.
The way this is possible is that the client *does* need to know about the set of possible media types it might receive.
If you retrieve a URI with your browser, the browser puts a bunch of stuff into the Accept header (html,xml mostly). Interestingly, it does not put image/* or text/css in there. Those types are only placed in the Accept header when the client is following an <img src=""/> or a <link rel="stylesheet"..> link.
Browsers vary of course and they also use */* but interestingly, they do not just put everything in there but use their knowlegde about the set of types to expect.
But again, if client assumes among other things some application/order+xml it can still not assume the presence of a certain link in the following response. Unless the link was mandatory part of any representation of that media type. (Which is a vary rare thing in media type specs and probably bad media type design).
And interestingly, it is only when we apply OO thinking to networked communication that we *think* a class definition could keep the server from evolving. A class definition can only ensure the caller about an object when the application is not distributed/networked.
REST just makes that explicit and keeps you from learning it the hard way - when your IDL defined services change or when you have to go through 'today we update all our clients and servers' routines.
Jan
>
>
>
>
>
-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting
Mail: algermissen_at_acm.org
Blog:
http://www.nordsc.com/blog/
Work:
http://www.nordsc.com/
-----------------------------------