RE: Modeling permissions with Hydra

On 9 Nov 2015 at 10:54, Asbjørn Ulsberg wrote:
> 2015-11-06 20:35 GMT+01:00 Ryan Shaw <ryanshaw@unc.edu>:
>> 1. There still doesn't seem to be consensus on the function of the API
>> documentation. Markus' position, if I understand correctly, is that
>> the API documentation is a kind of convenience or shortcut for
>> specifying state transitions; rather than or in addition to including
>> this information directly in representations. The advertised state
>> transitions from any specific representation are always the aggregate
>> of 1) the transitions specified in the representation itself PLUS 2)
>> any transitions specified in linked documentation.

This is not "my position". It is how it is currently defined. If you have a class C which supports operation O and a resource of type C, then a client can infer that the resource supports O.

   C hydra:supportedOperation O
   R rdf:type C
  ==> R operation O

I'm open to discuss this. The reason this was designed this way is that in most APIs out there, typically (almost) all instances of a specific type typically support exactly the same operations. You don't see a lot of APIs where each resource behaves completely differently from every other resource exposed by the API.


> I respectfully disagree with this view.
> 
>> 2. However at least some others think the API documentation should be
>> interpreted as a kind of overview of what might be possible; a way to
>> document an API using RDF, but always subject to revision by the
>> information in an actual representation.

Could you explain how such a "revision" would or could look like in practice? Apart from adding or removing a class/property from a resource which is how the current design works (e.g., make something a EditableBlogPost instead of just a BlogPost=.


> I view it in this way, but perhaps from a different perspective. To
> me, the point of the ApiDocumentation is to make writing a client and
> GUI on top of a Hydra backed API easy. The ApiDocumentation tells you
> about every detail you need to cater to in your client application.

Be careful with the work *every* here. You will have a hard time documenting all details.


> You know from the documentation which button states you need, which
> error messages you need to handle, which error states each resource
> might end up in, etc.

Sure, it can give developers (and machines) a nice overview of the surface of the API.


> All this information is crucial to build a full-fledged and meaningful
> client application. This is the information that is given in human
> language in current API documentation formats such as Swagger[1] and
> API Blueprint[2]. It is crucial, but it is just a blueprint. It is
> what allows you to write your application, but in order to actually
> let hypertext be the engine of application state, the client will have
> to rely on inline hypermedia controls and react to HTTP status codes
> that can and will change dynamically.

The ApiDocumentation is not communicated out of band. So I don't see a problem for the client to consume and interpret it at runtime (apart from additional complexity).


>> I'm less and less sure that I see the use of having potential state
>> transitions advertised anywhere *other* than in representations,
>> except as a way of generating human-readable documentation.

Fair enough. You will similarly find enough people that argue that most of their resources look and behave the same and they see little value in repeating this information everywhere. They want to put it in a central place and just reference it instead (just like the do with CSS for instance).


> Exactly.
> 
>> A Hydra client is always going to have to be ready to look for
>> advertisements of possible state transitions in individual
>> representations anyway; so what is the use of complicating client
>> implementation by saying, "hey, here are some other places to look
>> for possible state transitions"?
> 
> It makes the initial building of the client easier, since you only need
> one place of reference to build it. But as the client matures and
> discovers more about how the server behaves through the server-driven
> dialogue, it will grow smarter through the inline hypermedia controls.
> Because, let's face it; no matter how smart ApiDocumentation is and how
> complete someone who has written it feels it is, it *will* be incomplete.
> 
>> Why not just leave it at "state transitions are advertised in
>> representations, period"? What would be the drawbacks of dropping
>> hydra:supportedOperation from the core vocabulary?

I hope my comments above explain it.


> Yes, I think they are valuable. They just need to be interpreted as
> "possible operations your GUI should have built in support for", not
> "these are always possible to perform unless you try and the API
> returns a status code of 400 or higher".
> 
> 2015-11-06 21:36 GMT+01:00 Tomasz Pluskiewicz <tomasz@t-code.pl>:
> 
>> Good point. I accepted Markus' arguments before but what you write does make
>> sense. Common example of Hypermedia-driven API, often raised on this list,
>> is HTML+browser. All controls are included in the representation; ie. there
>> is no documentation.
> 
> Indeed.
> 
>> The browser however "knows" how to take user's input by presenting appropriate
>> elements, such as <input type="date">.
> 
> I don't see why hydra:ApiDocumentation can't include the same
> semantics. Specifying that a property is a https://schema.org/Date
> could yield the same front-end GUI, no?
> 
>> I think this is closest to the notion of API documentation, albeit very limited,
>> because browsers natively only support a very basic set of known input types.

That's gonna change dramatically with Web Components.


> I think that limitation is due to the bottleneck of the HTML
> specification process and not due to the platform of HTML having
> limited use for input (or data) types. With Hydra and RDF, we have a
> distributed way to declare input types that can be handled by
> standardized input components through generalized Hydra clients such
> as Karol Szczepański's URSA[3].
> 
>> If we were to align Hydra in similar fashion, all affordances could be
>> always included in the representation, which indeed removes part of the
>> burden from the client. What the ApiDocumentation would hold are all the
>> descriptions of supported types (shapes?).
> 
> Yes!
> 
>> The only problem I see would be with operations supported by (is that
>> the proper expression?) specific properties.
> 
> I'm not sure I understand what you mean with this, so please elaborate.
> 
>> Bottom line is, that last case may actually make it impossible to completely
>> move operations to individual resources.

No, that would always be possible.


>> Even worse, you could also include
>> supported operations in representations of your API's terms when
>> dereferenced, which may or may not each redirect to a different document
>> depending on a particular setup.
> 
> If different client implementors have different access rights to the
> API, their credentials can be used to differentiate the ApiDocumentation
> (and runtime resource) operations to tailor it to their needs. I see
> this as a way to simplify the documentation to only include what the
> implementor has access to, which is a very valid use case.
> 
> 2015-11-07 12:21 GMT+01:00 Karol Szczepański <karol.szczepanski@gmail.com>:
> 
>> Good point, but well, this approach is also known as world's best structured
>> data shredder. That's why there is no crawler capable of doing anything else
>> that HTTP GET as there is documentation and having hypermedia controls with
>> actual content pollutes the content.
> 
> Well, HTML is a document format tailored for human consumption, so
> that's why it works so well for that use-case and so bad for
> machine-to-machine communication. That doesn't outrule the possibility
> to express hypermedia controls in the same way in other, more
> structured and data-focused formats like JSON, though.
> 
>> I personally acknowledge hypermedia controls embedded in my data as a
>> pollution and I'm keen to get rid of then to a separated payload
> 
> Why? This requires the client to perform an extra GET or HEAD request
> to the referenced resource in order to figure out what it can do with
> the current. What other reasons than "purity" is the purpose of adding
> this N+1 complexity to your API?
> 
>> Also, from ReST point of view client should send back the resource,
>> but I'd argue whether hypermedia controls should be sent back as
>> these usually are not the part of the resource from data point of view.
> 
> REST doesn't mandate where the hypermedia controls should exist, only
> that they should be connected to the resource. The most optimal way to
> do this is to include the operations in the representation itself. I
> don't see this as a problem.
> 
>> I'm quite advanced in a proof-of-concept business application that heavily
>> utilizes API documentation to build user experience. I hope to have it
>> presented in next few days/weeks.
> 
> Is this the URSA project you wrote about a few days ago?
> 
>> Personally I see that both API documentation and hypermedia controls should
>> be complementary to each other. Documentation is a good starting point for a
>> client on where to start, what can be done, hypermedia should drive it's
>> behaviour once in the middle of the communication chain.
> 
> Yep. I agree.
> 
> ____
> [1] http://swagger.io/
> [2] https://apiblueprint.org/
> [3] https://github.com/alien-mcl/URSA


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 10 November 2015 21:43:15 UTC