List of supported use cases for compliant and conditionally compliant client

Hi,

Here is a list of user stories I would like to see.

Assumptions:
- the semantics of data attributes other than hydra data must not be
hardcoded into the client. It should be able to achieve a goal with any
hydra API
- the programmer informs the client about the next goal it should
achieve by giving it a predicate path and a set of data to apply at
specific steps in the path
- the client should behave mostly as a machine client, with human
interaction only at steps where the machine has insufficient information.
- the client uses hypertext as the engine of application state, i.e. it
follows links using a set of uniform methods on resources in order to
realize application use cases
- the client may rely on method semantics to retry failed transitions
automatically
- the client is recommended to cache responses according to cache info

1. As a programmer, I want to use the client to navigate to an API entry
page and get data enclosed in the entry page which the client recognizes
by their linked data name.
a) the data are a single item (:Organization :address -> client allows
access to :address as text or :PostalAddress as linked data)
b) the data are a collection (:Organization :makesOffer -> client allows
access to :Offer collection as linked data)

2. As a programmer, I want to use the client to navigate to an API entry
page and have the client recognize and follow a link in the API entry
page which it can recognize by its linked data name, making the received
representation the current one (:Organization :makesOffer ->client
retrieves offers as linked data as new application state)

3. As a programmer, I want to navigate to an API entry page and
transparently follow a chain of links or enclosed data, guided by their
linked data names. (:LocalBusiness :parentOrganization :contactPoint
:telephone -> client turns up one or more :ContactPoint items with
telephone numbers as linked data)

4. As a programmer, I want to use the client to POST to the API by
giving it linked data to POST and a path of predicates which leads to a
representation that has a POST hydra operation.

5. As a programmer, I want to use the client to PUT data to the API by
giving it linked data to PUT (replace) and a path of predicates which
leads to a representation that has a PUT hydra operation.

6. As a programmer, I want to use the client to PATCH (partial update) a
resource by giving it a path of predicates which leads to a
representation that has a PATCH hydra operation. (e.g. setting an
:eventStatus to :EventCancelled)

7. As a programmer, I want to use the client to POST to the API by
giving it *incomplete* linked data to send and a path to a
representation with a POST operation.
Given that the client does not have all information required for the
POST, when it detects the missing data, then it asks for additional data
including possible choices via a callback. The callback contains a data
structure which can be used to generate a UI or a CLI prompt.

8. As a programmer, I want to use the client to identify one or more
specific items in a collection by giving the client a path to the
collection with required data to follow the path, and matching criteria
to apply to the collection.

... to be continued, flamed against etc. at will ;-)

A final statement: We need to be precise about compliance for each use
case. Mike Amundsen distinguishes unconditionally and conditionally
compliant implementations [1]:

> An implementation is not compliant if it fails to satisfy one or more
of the MUST or REQUIRED elements. An implementation that satisfies all
the MUST and REQUIRED elements as well as all the SHOULD and RECOMMENDED
elements is said to be "unconditionally compliant"; one that satisfies
all the MUST and REQUIRED elements but not all the SHOULD and
RECOMMENDED elements is said to be "conditionally compliant."

I think such a definition is needed to establish a level of
interoperability servers can rely on, and it can help us to resolve
disagreements about use cases, by making things conditional which not
everybody can agree upon.

Best regards,
Dietrich


[1]
https://github.com/mamund/media-types/blob/master/uber-hypermedia.asciidoc#23-compliance

Received on Friday, 17 June 2016 08:46:05 UTC