Subject: [GNAP] API discovery

From: Denis <[email-masked]>
Date: Mon, 24 Aug 2020 10:19:38 +0200

To the list,

**A discovery mechanism should be usable to discover which actions are 
possible on the RS.

This can be seen as a means to implement some aspects of the level 3 of 
the Richardson Maturity Model (RMM):
HATEOAS (Hypermedia as the Engine of Application State) but combined 
with access control, i.e. knowing at the same time
which actions that can be done and the access control characteristics 
associated with these actions which is an aspect
that is not addressed in HATEOAS.

Such an API discovery mechanism could be used before or after 
authentication has been achieved on the RS.

If the API discovery mechanism is used before authentication has been 
achieved, the RS might indicate that no operation is available
at this time which would means that the available operations will only 
be disclosed once authentication has been achieved.

See the simple example from : https://en.wikipedia.org/wiki/HATEOAS 
which is using a GET request.
It is important to notice in that example that the allowed actions that 
are possible varies dynamically as the state of the resource varies.

Using an appropriate HTTP OPTIONS request, the client (or its User) 
should be able to know:

  * which actions that can be done (i.e. which methods are available on
    which data objects), and
  * the access control characteristics associated with each of these
    actions (i.e. which ASs are being trusted by the RS
    and what should be incorporated into access token(s) in terms of
    attributes types (and optionally attribute values)
    or in terms of capabilities (i.e. permissions granted by a Resource
    Controller).

In the case where the request is made on behalf of a User, this 
information should be usable by the User Agent of the client in order to 
capture the User Consent.
The selection made by the User should then be sent back to the client, 
so that the client would be able to request the appropriate access 
tokens from the appropriate ASs.

Then after, at every step further in the processing of a transaction, 
the client would be able to issue another HTTP OPTIONS request.

A client supporting JavaScript would be able to take a full advantage of 
such an approach. Using an appropriate format indication in the HTTP 
OPTIONS request,
it would even be possible to get a response directly processable under a 
client supporting JavaScript.

A less ambitious approach would be to tell to the client the access 
control rules that apply once an operation has been selected
(instead of before the operation has been selected).

Denis