Re: How much REST should your Web API get?

On May 4, 2013, at 12:47 PM, "Markus Lanthaler" <[email protected]> wrote:
> That has nothing to do with statelessness as it describes what the client is
> doing. The request to the server definitely contains all information and
> doesn't rely on a shared state. So no, this is not stateful. Not even if
> there are 100s of requests in between. The server and any intermediary
> couldn't care less.
> 
> As long as that document is evaluated at run-time and not at design- or
> compile-time everything is fine. Otherwise the result would be a client that
> is tightly coupled to the server.
> 
> Yeah. The emphasis is on "next application state". That doesn't require that
> the next state is the final state. So there can be as many steps in between
> as there are required... and every response to those intermediary requests
> can link back to the home document - just in case the client hasn't seen it
> yet. That's exactly the same as for normal websites.


Hmm.  Okay, the more I think I understand about REST the more I think I don't understand and/or am unsure who actually really understands REST besides Roy.

As I've read Roy I've come away understanding that messages must be self-contained and the only thing the client should know is how the links in the returned representation are defined to behave as defined by the representation's content yype. Having links in one document and data in a second document where you have to have the contents of both documents seems to me to violate that need for self-containment.

Honestly I want you to be right; the idea of a service document that contains all the API URLs and URI templates so that the other messages can all be lightweight is very compelling.

I do have one question; if there is a home document that is cacheable for some period "X" and at the time immediately after an API client retrieves the home document the servers are moved and the client later perform an operation that requires URLs from the home document but before "X" time has passed, it can cause failure.  If the message is self-contained that time window is greatly reduced. This is one of the reasons I can postulate there is a need for self-contained messages.

-Mike