Include text on changing control flow with HATEOAS

[mkovatsc]

Hypermedia allows the server to redirect or introduce new links that are presented to the client to change the application during runtime. Client and server can evolve independently.

[ektrah]

To expand a bit on this, there are multiple reasons why a server might introduce new links or forms:

• The server implements a newer version of the application. Older clients ignore the new links and forms, while newer clients are able to take advantage of the new features by following the new links and submitting the new forms.
• The server offers links and forms depending on the current state. The server can tell the client which operations are currently valid and thus help the client navigate the application state machine. The client does not have to have knowledge which operations are allowed in the current state or make a request just to find out that the operation is not valid.
• The server offers links and forms depending on the client's access control rights. If the client is unauthorized to perform a certain operation, then the server can simply omit the links and forms for that operation.

[mkovatsc]

Extensibility at runtime

[mkovatsc]

Not too much details, but current best practices, since this will be outcome of the RG.

[mkovatsc]

Related comment by Mike Amundsen:

Flow control MAY be managed from either the client ("please set this valve to position 3") or the resource server ("According to my configuration data, your client certificate only allows you to do one of the following...") Rather than try to define "session state" as flow control, I think it s better the establish lines of responsibility for client state and resource state.

[mkovatsc]

Mike Admundsen:

I suggest the following updated wording for the opening: "Important part of designing a system is to model is as a set of resources which represent the "state of the system." Clients MAY be allowed to modify the state of resources by passing representations to the server (using request bodies). Servers manipulate the state of clients by passing representations of resources (using response bodies)."

I have a different conception of the second part: Servers cannot manipulate the state of clients directly. Clients have the initiative for what to do with received representations (they do not expose their internal state as resources!). I find the aspect more important that servers provide the possible state transitions through the announcement of links and forms.

[mkovatsc]

This issue is addressed through Section 5.

The comments do not apply anymore to the current version. They should be verified during a holistic review of the document.