Fwd: Step by step resource editing

Hi Marcus,

Thanks for the reply.

[Replying to this in Web mail, I hope the inline comments look right
otherwise I'll repost]

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 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.

> ... 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.”*

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.

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)?

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?

> ... 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).



> > 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!


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

Thanks,

Kev

[1] RESTful Web APIs, OReilly Media

-- 
www.dataunity.org
twitter: @data_unity



-- 
www.dataunity.org
twitter: @data_unity