diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index f186896..5a91e3d 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -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", @@ -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" }, @@ -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" @@ -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" @@ -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" diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html index e1a210c..9aff512 100644 --- a/spec/latest/core/index.html +++ b/spec/latest/core/index.html @@ -744,6 +744,84 @@
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 retractedOperation predicate that can be added to the reasorce + the same way as the operation 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 + Unavailable or Unauthorized with a reason 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 + Hydra built in reasons.
+ +The retractedOperation MUST NOT be used in context of the ApiDocumentation. + The retractedOperation predicate also MUST take precedence over both + operation and supportedOperation declaration and overrides them. + The operation that comes with retractedOperation predicate SHOULD be identified + using any of the below enlisted methods: +
+ ++
+ ++ +
In the example above the operation that expects an uploaded file became + Unavailable, while the one expecting a comment remains available as + the expects 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.
+These are the simple example scenarios and possible usages are not limited to those described above.