Skip to content
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

Jump to bottom

Retracting operations #246

Open
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 all 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
66 changes: 62 additions & 4 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,12 @@
"method": "hydra:method",
"expects": { "@id": "hydra:expects", "@type": "@vocab" },
"returns": { "@id": "hydra:returns", "@type": "@vocab" },
"retractedOperation": { "@id": "hydra:retractedOperation", "@type": "@vocab" },
"reason": { "@id": "hydra:reason", "@type": "@vocab" },
"RetractedOperationSpecification": "hydra:RetractedOperationSpecification",
"UnavailabilityReason": "hydra:UnavailabilityReason",
"Unavailable": "hydra:Unavailable",
"Unauthorized": "hydra:Unauthorized",
"possibleStatus": { "@id": "hydra:possibleStatus", "@type": "@id" },
"Status": "hydra:Status",
"statusCode": "hydra:statusCode",
Expand Down Expand Up @@ -167,13 +173,65 @@
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:retractedOperation",
"@type": "rdf:Property",
"label": "retracted operation",
"comment": "Retracts available operations.",
"range": "hydra:RetractedOperationSpecification",
"domain": "hydra:Resource",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:RetractedOperationSpecification",
"@type": "hydra:Class",
"label": "retracted operation specification",
"comment": "Describes which and why an operation is retracted.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:reason",
"@type": "rdf:Property",
"label": "reason",
"comment": "Reason of why the operation is retracted.",
"range": "hydra:UnavailabilityReason",
"domain": "hydra:RetractedOperationSpecification",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:UnavailabilityReason",
"@type": "hydra:Class",
"label": "Unavailability reason",
"comment": "Provides reasons why the operation cannot be invoked.",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
{
"@id": "hydra:Unavailable",
"@type": "hydra:UnavailabilityReason",
"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:possibleStatus",
"@type": "hydra:Link",
"label": "possible status",
"comment": "A status that might be returned by the Web API (other statuses should be expected and properly handled as well)",
"range": "hydra:Status",
"domainIncludes": ["hydra:ApiDocumentation", "hydra:Operation"],
"domainIncludes": ["hydra:ApiDocumentation", "hydra:Operation", "hydra:RetractedOperationSpecification"],
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
},
Expand Down Expand Up @@ -276,7 +334,7 @@
"@type": "rdf:Property",
"label": "method",
"comment": "The HTTP method.",
"domain": "hydra:Operation",
"domainIncludes": ["hydra:Operation", "hydra:RetractedOperationSpecification"],
"range": "xsd:string",
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
Expand All @@ -286,7 +344,7 @@
"@type": "hydra:Link",
"label": "expects",
"comment": "The information expected by the Web API.",
"domain": "hydra:Operation",
"domainIncludes": ["hydra:Operation", "hydra:RetractedOperationSpecification"],
"rangeIncludes": ["rdfs:Resource", "hydra:Resource", "rdfs:Class", "hydra:Class"],
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
Expand All @@ -296,7 +354,7 @@
"@type": "hydra:Link",
"label": "returns",
"comment": "The information returned by the Web API on success",
"domain": "hydra:Operation",
"domainIncludes": ["hydra:Operation", "hydra:RetractedOperationSpecification"],
"rangeIncludes": ["rdfs:Resource", "hydra:Resource", "rdfs:Class", "hydra:Class"],
"isDefinedBy": "http://www.w3.org/ns/hydra/core",
"vs:term_status": "testing"
Expand Down
78 changes: 78 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,84 @@ <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>retractedOperation<i> predicate that can be added to the reasorce
the same way as the <i>operation</i> is. By default all operations are available
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> with a <i>reason</i> predicate.
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>The <i>retractedOperation</i> MUST NOT be used in context of the <i>ApiDocumentation</i>.
The <i>retractedOperation</i> predicate also MUST take precedence over both
<i>operation</i> and <i>supportedOperation</i> declaration and overrides them.
The operation that comes with <i>retractedOperation</i> predicate SHOULD be identified
using any of the below enlisted methods:
<ul>
<li>Iri by using <i>object</i> predicate</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",
"retractedOperation": [
{
"@type": "Operation",
"method": "POST",
"expects": "http://api.example.com/doc/#Upload",
Copy link
Contributor

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
Contributor

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
Member Author

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

"reason": "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