Re: Modeling permissions with Hydra

On 2015-11-06 20:35, Ryan Shaw wrote:
>
> Thanks to everyone who has contributed to this thread; great discussion.
>
> My takeaways so far:
>
> 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.
>
> 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.
>
> 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. 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"?
> 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?
 >

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. The browser however 
"knows" how to take user's input by presenting appropriate elements, 
such as <input type="date">. 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.

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?). The only problem I see would 
be with operations supported by (is that the proper expression?) 
specific properties.

Bottom line is, that last case may actually make it impossible to 
completely move operations to individual resources. 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.

>
> Ryan
>

Received on Friday, 6 November 2015 20:37:32 UTC