Skip to content

Retracting operations #246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alien-mcl wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Retracting operations #246

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ef633c4
Adding operation availability terms.
alien-mcl Aug 29, 2022
7bc4d71
Replaced Forbidden with Unavailable
alien-mcl Dec 11, 2022
5f85c8a
Revamped whole feature according to code review - or I hope so
alien-mcl Feb 25, 2023
594c072
Fixed formatting issues
alien-mcl Feb 25, 2023
7816931
Fixed missing JSON commas
alien-mcl Nov 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions spec/latest/core/core.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"method": "hydra:method",
"expects": { "@id": "hydra:expects", "@type": "@vocab" },
"returns": { "@id": "hydra:returns", "@type": "@vocab" },
"availability": { "@id": "hydra:availability", "@type": "@vocab" },
"possibleStatus": { "@id": "hydra:possibleStatus", "@type": "@id" },
"Status": "hydra:Status",
"statusCode": "hydra:statusCode",
Expand Down Expand Up @@ -167,6 +168,48 @@
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:availability",
"@type": "rdf:Property",
"label": "availability",
"comment": "Availability of the operation explicitely stated.",
"range": "hydra:Availability",
"domain": "hydra:Operation",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:Availability",
"@type": "hydra:Class",
"label": "Availability",
"comment": "Availability states when the operation can be invoked.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:Unavailable",
"@type": "hydra:Availability",
"label": "Unavailable",
"comment": "States an operation previously announced is unavailable in current circumstances.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:Unauthorized",
"@type": "hydra:Availability",
"label": "Unauthorized",
"comment": "States an operation previously announced should not be invoked as the current user is not authorized to invoke it.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:Available",
"@type": "hydra:Availability",
"label": "Available",
"comment": "States an operation is available for invocation. This is a default operation availability.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:possibleStatus",
"@type": "hydra:Link",
Expand Down
77 changes: 77 additions & 0 deletions spec/latest/core/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -744,6 +744,83 @@ <h3>Documenting a Web API</h3>
without elevating it to the <i>Link</i> SHOULD NOT be implemented as clients
may not discover such a construct correctly.</p>

<p>There are rare situations when some supported operations once announced in the
API documentation should be retracted, i.e. to reflect current state of the
application or current user capabilities (or lack of them). It is doable
with the <i>availability<i> predicate that can be added to the <i>Operation</i>
itself. By default all operations are <i>Available</i> without limits and it
is up for the server to change that, and for the client to discover any
discrepancies compared against the API documentation in the runtime. Yet
server may want to inform the client that at the very moment an operation is either
<i>Unavailable</i> or <i>Unauthorized</i>. The latter MAY be used to notify
client that the user used to invoke the request that provides operation
availability information is currently not authorized for that very operation
to be invoked. The former on the other hand MAY be used to inform that
the operation is currently forbidden and client SHOULD NOT invoke it.
Server MAY also provide more custom reasons for which the operation is not
available but it SHOULD provide at least one of the <i>Hydra</i> built in reasons.</p>

<p>Usage of the <i>availability</i> is restricted only to the <i>Operation</i>s
and MUST NOT be used on <i>SupportedOperation</i>s. The <i>availability</i>
predicate also MUST take precedence over a supported operation declaration.
The operation that comes with <i>availability</i> predicate SHOULD be identified
using any of the below enlisted methods:
<ul>
<li>Iri</li>
<li>exact match of a resource described by <i>possibleStatus</i>, <i>method</i>,
<i>expects</i>, <i>returns</i> or combination of those.</li>
</ul>
</p>

<pre class="example nohighlight" data-transform="updateExample"
title="Retracting operations - declaration of supported operations">
<!--
{
"@context": "http://www.w3.org/ns/hydra/context.jsonld",
"@id": "http://api.example.com/doc/#comments",
"@type": "Link",
"supportedOperation": [
{
"@type": "Operation",
"method": "POST",
"expects": "http://api.example.com/doc/#Upload"
},
{
"@type": "Operation",
"method": "POST",
"expects": "http://api.example.com/doc/#Comment"
}
]
}
-->
</pre>
<pre class="example nohighlight" data-transform="updateExample"
title="Retracting operations - matching">
<!--
{
"@context": "http://www.w3.org/ns/hydra/context.jsonld",
"@id": "http://api.example.com/doc/",
"@type": "Collection",
"operation": [
Comment thread
alien-mcl marked this conversation as resolved.
Outdated
{
"@type": "Operation",
"method": "POST",
"expects": "http://api.example.com/doc/#Upload",
Copy link
Copy Markdown
Contributor

@tpluscode tpluscode Jan 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does that even work? By matching hydra:expects? That doesn't seem right...

Copy link
Copy Markdown
Contributor

@tpluscode tpluscode Jan 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have expected (no pun intended), to retract by rdf:type

Copy link
Copy Markdown
Member Author

@alien-mcl alien-mcl Nov 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As described above - idea is to either match by the operation iri or exact match of the predicates enlisted

"availability": "Unavailable"
}
]
}
-->
</pre>

<p>In the example above the operation that expects an uploaded file became
<i>Unavailable</i>, while the one expecting a comment remains available as
the <i>expects</i> predicate does not match any supported operations.
It is still recommended to mark operations being subject for further
restrictions with an Iri as from the client perspective this may be
easier to implement simple literal Iri comparison rather than to compare
graphs of objects.</p>

<p>These are the simple example scenarios and possible usages are not
limited to those described above.</p>

Expand Down