search

webapi-discovery / rfcs

w3c WebAPI Discovery Community Group - Request For Comments
https://webapi-discovery.github.io/rfcs
The Unlicense
4 stars 1 forks source link

suggested 'potentialActions' are links, not actions #12

Open smrgeoinfo opened 4 years ago

smrgeoinfo commented 4 years ago

Suggestions for potentialActions (API console, API SLA, and API Support, API Authentication, API Payment) are not actions on the API, but links to related resources. isRelatedTo is an obvious property for these cases. The example in Section 5 has a potentialAction that has a different endpoint from the endpointUrl. This should be an isRelatedTo link to a Service for API client Registration.

MikeRalphson commented 4 years ago

I believe we were explicitly steered towards using Actions for this. They are intended to be follow on (potential) actions to the discovery process. isRelatedTo sounds somewhat vague (especially given the description "A pointer to another, somehow related product (or multiple products).") whereas I agree what we might want is something along the lines of the HTTP Link header rel (relation-type). @nickevansuk thoughts?

nickevansuk commented 4 years ago

It's a bit of a philosophical point, but my understanding is that potentialActions are designed to affect the intended object via a website or app deep link, rather than directly.

When using TrackAction to track the ParcelDelivery, the target in the example takes you to http://fedex.com/track/1234567890, and hence the mail client (in this case) displays a link to http://fedex.com/track/1234567890. The client does not interact with the physical parcel itself, but instead with the service that delivers the parcel.

Hence when using RegisterAction to register for access to a WebAPI, the target in the example takes you to https://developers.google.com/knowledge-graph/how-tos/authorizing, and hence the API aggregator client displays a link to https://developers.google.com/knowledge-graph/how-tos/authorizing. The client does not interact with the actual API itself, but instead with the service that delivers the API.

Apologies for the contrived analogy, but hopefully helps clarify!

nickevansuk commented 4 years ago

Also isRelatedTo would be more useful to link to alternative API versions (as per https://github.com/schemaorg/schemaorg/pull/1445#issuecomment-265199747)