Re: Modeling permissions with Hydra

2015-11-06 20:35 GMT+01:00 Ryan Shaw <ryanshaw@unc.edu>:

> The relevant thread starts here:
> https://lists.w3.org/Archives/Public/public-hydra/2014Jun/0054.html
>
> And continues here:
> https://lists.w3.org/Archives/Public/public-hydra/2014Jul/0024.html
> https://lists.w3.org/Archives/Public/public-hydra/2014Jul/0027.html

Thanks for the pointers.

> Thanks to everyone who has contributed to this thread; great discussion.

I agree!

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

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.

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

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.

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

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?

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.

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

-- 
Asbjørn Ulsberg           -=|=-        asbjorn@ulsberg.no
«He's a loathsome offensive brute, yet I can't look away»

Received on Monday, 9 November 2015 09:55:30 UTC