[client-interface] Suggestion for browser-like client API

dschulten commented 7 years ago

PR to show how a browser-like client could behave

RubenVerborgh commented 7 years ago

For what languages is the interface?

Is an entrypoint necessary?

What is the "current" representation?

dschulten commented 7 years ago

The sample cli is written in pseudocode. It makes use of a hypothetical hydra object which has certain property accessors and methods. Notably:

setLocation: the equivalent of entering a url in the address bar
representation: access to the header and body received after requesting the most recent resource, i.e. the current application state
controls: access to hypermedia affordances in the current representation
execute: make use of a given hypermedia affordance to transition to another representation, i.e. application state.

The interaction with the hypothetical hydra client uses these accessors and methods by means of the pseudo language. A real hydra object would of course need accessors and methods for a real language.

The findEntrypoint method is not necessary, as stated by the hydra spec.

The current representation is usually the result of an interaction with a server resource identified by a URI (unless the interaction was fulfilled from a local cache). E.g. a GET for a URI may result in a response which is a representation of the requested resource.

tpluscode commented 7 years ago

That's more how I started with heracles. You can start with any resource URL and get a Hydra resource object with hydra:stuff mapped to nice JS getters. It will be possible to define custom extension so that it won't be necessary to work with full URIs name.

Here's the direction I want to go

import {Hydra} from 'heracles';

Hydra.loadResource('http://example.com/user/tpluscode')
  .then(res => {
    // contains the entrypoint, supported classes and operations, and other Api Doc stuff.
    var apiDocs = res.apiDocumentation;

    // same as res['@id']
    var id = res.id; 

    // let's assume the operation is available
   var op = res.operations["http://example.com/vocab#updateName"];

    return op.invoke({
        'name': 'Tomasz'
    });
  }).then(doSomethingWithTheOperationResult);

As you see there is no state. Or rather, there are only Hydra resource

On the other hand it now dawns on me that I intend to create a Hydra library and not a client right?

RubenVerborgh commented 7 years ago

I find the interaction with the "hypothetical hydra object" a bit strange; it's a weird abstraction from a browser. What are reasons to prefer this over a resource-based abstraction, where one resource provides access to others?

Also, setLocation, brrr hypermedia :wink:

dschulten commented 7 years ago

Well it is clear that so far no one shares my idea of a hydra client interface. I have no problem with that. I want us to make progress here, not to defend my ideas.

My focus is to get a reference client implementation so that we can verify the Hydra spec and find out what is really needed. I do not think it is essential for the purpose of verification of the Hydra vocab which metaphor the client abstraction uses or which method signatures it has. We are again splitting hairs, and I am not going to waste any more time on that.

How about someone else spells out his idea of a client interface? Or can we just adopt heracles as the reference client?

Can we please decide anything which moves us forward? I am extremely frustrated with the way the group un-collaborates. No offense intended.

asbjornu commented 7 years ago

I really like the idea behind this. Having a reference implementation as an informational (non-normative) appendix in the spec would be great. But why does this reference implementation have to be pseudo code? Can't it instead be a real-world client implementation?

One way to do this would be to move Heracles to the @HydraCG organisation and make it work as a foundation for our client-side endeavours. This client could then be offered up as a way to verify server implementations, sort of like "Atom Application Exerciser" (APE; developed by @timbray) worked back when we developed the Atom Publishing Protocol.

RubenVerborgh commented 7 years ago

Well it is clear that so far no one shares my idea of a hydra client interface. I have no problem with that.

It might very well be the best idea, so please explain it that we all are able to understand.

I want us to make progress here

Then it is very important that we all understand :-)

So could you please give my question another take?

What are reasons to prefer this over a resource-based abstraction, where one resource provides access to others?

RubenVerborgh commented 7 years ago

Can we please decide anything which moves us forward? I am extremely frustrated with the way the group un-collaborates. No offense intended.

BTW I share your concern; my architecture e-mail still remains unanswered.

I think having a client is a great idea—perhaps even a very good starting point for a 1.0 spec. But in that sense, the client spec proposed here can also be seen as "splitting hairs", as it zooms in on very detailed aspects before getting the bigger picture straight.

How about we (= whoever wants to contribute to Hydra) have a conf call to sync on this?

dschulten commented 7 years ago

@tpluscode is it an option to let Heracles be the reference client? If so, can we move it, or a fork of it, to the HydraCg organization?

tpluscode commented 7 years ago

is it an option to let Heracles be the reference client?

I don't see why not, in principle. But I hope you didn't get my comment the wrong way. I simply meant that I feel that the kind of client @RubenVerborgh was describing is more natural to me. It is more of an experiment in that I flesh it out as I go. I first added some stuff, then tried to use it, and then refactored. The effect may not be 100% how I'd like it and some code is not pretty ;)

But why does this reference implementation have to be pseudo code?

I kind of think it's a good idea up to some point. For now I'm actually in favor of a language-agnostic draft of how we agree such a Hydra client would be implemented and APIs consumed. This way we can at least avoid some intricacies of processing JSON-LD. At least for now. It could also help us decide on some pieces of Hydra by investigating whet client can do rather than how we imagine the vocabulary. I may have some insight after starting with Heracles and so would other people that already started some client implementation. Some names include @antoniogarrote, @bergos, @dunglas, @pchampin, @Mec-iS. Can we get you guys on board?

How about we have a conf call to sync on this?

Yes, please

RubenVerborgh commented 7 years ago

How about we have a conf call to sync on this? Yes, please

I'll await some more comments, but plan to send out such a mail this week on the Hydra mailing list.

dunglas commented 7 years ago

Hi guys, I'll announce a parser for the Hydra documentation, an admin generator (using Admin On Rest) and a CRUD generator (scaffolding an app built with React and Redux) Friday during the Symfony Live conference.

The code is already publicly available:

The parser: https://github.com/dunglas/api-doc-parser
The admin: https://github.com/api-platform/admin
The CRUD generator: https://github.com/api-platform/generate-crud

Both tools are designed to rely on an intermediate representation to be able to support other API docs formats (Swagger, API Blueprint...). Hypermedia features of Hydra aren't 100% supported yet but I think it's a good start. It would be nice to have some rock solid JS libraries to create apps, it will help onboarding new developers.

lanthaler commented 7 years ago

Wow, I didn't intend to side-track this PR so much. My reaction (and perhaps the one of others too) was solely triggered by the fact that I expected the Hydra client library to be something lower level. I'd suggest we call that out explicitly in the doc, merge this PR and iterate.

Thanks a lot @dschulten for taking the lead on this and please bear with us. The amount of feedback you received shows that people definitely care about your work.

tpluscode commented 7 years ago

I agree. Both client library and Hydra Client (capitalized) have their place.

dschulten commented 7 years ago

@lanthaler the original version guided me to believe that the document should not just outline an interface but show a pseudocode application which makes use of the hydra client library:

Retrieve a resource

resource = hydra.download(url)

I see an application there which uses the hydra client, and that approach makes sense because it allows you to think about the interface from the caller's perspective. The PR in all its shortness goes full circle in that it tries to cover all cases where the caller needs to work with server expectations: uri templates, headers and request bodies.

If somebody else would rather write a totally different initial PR and actually tasks himself to do it very soon, let's wait. Otherwise, we could continue with this PR and someone rewrites it so that hydraClient is only a starting point, returns a representation and the caller uses that representation abstraction for all further interaction.

Obviously it is not a good mode of operation if everybody tells me they had a very different idea, asking me to bring their idea to life - accompanied by jeers and catcalls ;-) Or at least that is how it felt on my end.

lanthaler commented 7 years ago

@lanthaler the original version guided me to believe that the document should not just outline an interface but show a pseudocode application which makes use of the hydra client library:

Yes, I indeed wanted to show how the client looks like in use. It doesn't need to be a full application. Some simple use cases (retrieve a resource, retrieve all items from a collection, execute an operation, etc.) should be enough. It helps to understand the usability of the interface.

If somebody else would rather write a totally different initial PR and actually tasks himself to do it very soon, let's wait.

No, we definitely shouldn't do that IMO :-)

Obviously it is not a good mode of operation if everybody tells me they had a very different idea, asking me to bring their idea to life - accompanied by jeers and catcalls ;-) Or at least that is how it felt on my end.

Well, we will need to have some discussions at some point. Since the group decided to move most of the work to GitHub, a PR feels like a good opportunity to have such a discussion. Don't see it as criticism but as constructive feedback. It's your PR, so feel free to push back, address it by leaving a note or todo in the doc or something else. I'm actually really happy to see such lively discussions again but I can imagine how it may have felt on your end.

So, to move forward I'd suggest to go through the comments and address them in whatever way you feel is appropriate. Adding a section "open questions" or something along those lines would work quite well for lots of them given that this is a working doc. We can then merge this and someone else can pick up one of the questions or make changes to the doc that we will then discuss separately.

Does that sounds like a reasonable way forward?

RubenVerborgh commented 7 years ago

My two cents would be that:

This is too substantial to discuss in a pull request. We'd really need a repo for a client, so we can have a structured discussion.
We need a phone conf to discuss this and more. Brought this to the mailing list.

HydraCG / Specifications

[client-interface] Suggestion for browser-like client API #111

Retrieve a resource