RE: Step by step resource editing

On Wed, 17 Sep 2014 19:06:32 +0100, Kev Kirkland wrote:
> [Replying to this in Web mail, I hope the inline comments look right
> otherwise I'll repost]

It's ok but text-only mails are generally preferred for various reasons.


>> An alternative would be to model this as a workflow so that you
>> explicitly state what the next valid step(s) are. Something like:
>>
>>   OrderWorkflow
>>      --- firstStep --> WorkflowStep [Payment]
>>             ---> describes operation to execute this step
>>     on success returns new WorkflowStep [Address]
>>
>> It might actually be interesting to integrate something like that
>> into Hydra. I created ISSUE-70 [1] so that we don't forget this.
> 
> The case I'm thinking of involves routing (the steps are different
> depending on the user's choices as they go through the process) so
> Workflow might not be applicable (you probably don't want to make
> lots of workflows to cover all the permutations). However it might

What I described above, doesn't mean that you have to describe the
complete workflow a-priori. It was more intended to give you a
framework to communicate workflow steps at runtime. You start by
saying that ordering involves a workflow and how the first step looks
like. All subsequent steps are returned in response to the issued HTTP
requests.


> be useful for another user case I have in mind - editing a smaller
> portion of whole. I'll post this use case in a new email when I get
> round to it to avoid confusion.

OK


>>> ... how would the client know it needs to prompt the Hydra client
>>> for more information?
>>
>> Your client would need to be aware of the process
> 
> I've thought of a way to focus on the problem using an analogy from
> Mike Amundsen's API book [1]. When explaining HTTP 303 codes Mike
> uses the following story:
>
> *You go to a pharmacy with a prescription to be filled. A 303 is
> **the pharmacist saying “We’ve filled your prescription. Go to the
> next window to pick **up your medicine.”*

That works only to a certain degree. A 303 simply redirects you to a
different resource. Your client needs to be smart enough to know how
to interpret that resource and how to proceed from there to achieve
its goal.


> The situation I have in mind is the pharmacist saying "We've filled
> your prescription. Go to the next window and fill in a new form"
> (Maybe you have to fill in a new form saying you accept the risks of
> taking the medicine before it's given to you.) HTTP 303 tells us to
> 'go to the next' window, but it can't tell us to 'fill in the form'
> when we get there. I think this is a situation where Hydra can help.

Right. That's the scenario I had in mind with my workflow proposal.
The server basically informs the client upfront that multiple steps
might be required to achieve a certain goal and that it will guide the
client. Then, after each step, the server sends instructions for the
next step (a new workflow step).


> Stepping back a moment, I like what Mike calls 'The semantic
> challenge' for Hypermedia APIs. When using a website we (as a human)
> get clues that we need to keep supplying information when going
> through a process (like filling in forms during the order process in
> the original post). When we submit a form and see another form in
> front of us we think, 'OK, I need to fill this out form too so I can
> get to the end'. There may be other clues like some text saying
> 'step 1 of 3'. I guess the challenge is reproducing this in a
> Hypermedia API. How does a machine know that it is supposed to keep
> supplying information (until the server tells it it's got enough)?

Exactly. There are basically two solutions: either you make your
client smarter by teaching it more about the application domain (there
are orders, orders may require payment information and a shipping
address, etc.) or you generalize this teach your client how to execute
what I called a "workflows".


> I think the solution you mention below does this (if I interpret it
> correctly). That is we return a representation that has a single
> Hydra operation and the single operation is to POST some information
> using a SupportedClass?

Right. Your client, however, would also need to know that it has to
make a payment to complete an order (although it would be  nice to be
able to order things without having to pay :-)


>> ... I would simply embed the operations in its representation
>>  {
>>    ...
>>    "@type": "Order",
>>    "operation": {
>>      "method": "POST",
>>      "label": "Make payment",
>>      "expects": "vocab:PaymentDetails",
>>      "returns": "vocab:Order"
>>    }
>>  }
>>
>>  As soon as the user made the payment, you replace that operation
>>  with an operation to set the address.
> 
> The client would automatically go into 'form mode' when it sees that
> there is only one POST operation available (if it's a UI type
> client).

Yeah, that's one heuristic you could use.


>>> I'm building a Hydra Javascript client which mimics a Single Page Web
>>> Application
>>
>> Awesome! Do you already have something you can share with us?
> 
> Certainly happy to share. I just need to tidy up a few things before
> releasing it (it uses a hard coded API Doc url at the moment). I'll
> supply some more information when I release it, but I wanted to make
> a client that was purely javascript (I'm clueless when it comes to
> PHP!), that works like a Single Page Application and has features
> like forward/backward navigation using the browser buttons. Also a
> good way to really learn about the spec!

That sounds super interesting. I'm really look forward to learn more
about it soon.


>> Btw. it would be great if you could join the Hydra W3C Community
>> Group
>
> Done!

Fantastic. Welcome on board! :-)


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 17 September 2014 20:59:00 UTC