From ef633c467261b8bd25a571f2cb9d161ba9dab68a Mon Sep 17 00:00:00 2001 From: alien-mcl Date: Mon, 29 Aug 2022 17:41:31 +0200 Subject: [PATCH 1/5] Adding operation availability terms. --- spec/latest/core/core.jsonld | 43 ++++++++++++++++++++ spec/latest/core/index.html | 77 ++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index f186896..b77723c 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -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", @@ -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:Forbidden", + "@type": "hydra:Availability", + "label": "Forbidden", + "comment": "States an operation previously announced is forbidden 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", diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html index e1a210c..b5beabf 100644 --- a/spec/latest/core/index.html +++ b/spec/latest/core/index.html @@ -744,6 +744,83 @@

Documenting a Web API

without elevating it to the Link SHOULD NOT be implemented as clients may not discover such a construct correctly.

+

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 availability predicate that can be added to the Operation + itself. 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 + Forbidden or Unauthorized. 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.

+ +

Usage of the availability is restricted only to the Operations + and MUST NOT be used on SupportedOperations. The availability + predicate also MUST take precedence over a supported operation declaration. + The operation that comes with availability predicate SHOULD be identified + using any of the below enlisted methods: +

    +
  • Iri
    • +
  • exact match of a resource described by possibleStatus, method, + expects, returns or combination of those.
    • +
+

+ + 
+      
+
+ 
+      
+
+ +

In the example above the operation that expects an uploaded file became + Forbidden, 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.

From 7bc4d719ab765724eccba8f69d0c7291849c4236 Mon Sep 17 00:00:00 2001 From: alien-mcl Date: Sun, 11 Dec 2022 20:31:37 +0100 Subject: [PATCH 2/5] Replaced Forbidden with Unavailable --- spec/latest/core/core.jsonld | 8 ++++---- spec/latest/core/index.html | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index b77723c..2669676 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -172,7 +172,7 @@ "@id": "hydra:availability", "@type": "rdf:Property", "label": "availability", - "comment": "Availability of the operation explicitely stated", + "comment": "Availability of the operation explicitely stated.", "range": "hydra:Availability", "domain": "hydra:Operation", "isDefinedBy": "http://www.w3.org/ns/hydra/core", @@ -187,10 +187,10 @@ "vs:term_status": "testing" }, { - "@id": "hydra:Forbidden", + "@id": "hydra:Unavailable", "@type": "hydra:Availability", - "label": "Forbidden", - "comment": "States an operation previously announced is forbidden in current circumstances.", + "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" }, diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html index b5beabf..65a6a80 100644 --- a/spec/latest/core/index.html +++ b/spec/latest/core/index.html @@ -752,7 +752,7 @@

Documenting a Web API

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 - Forbidden or Unauthorized. The latter MAY be used to notify + Unavailable or Unauthorized. 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 @@ -806,7 +806,7 @@

Documenting a Web API

"@type": "Operation", "method": "POST", "expects": "http://api.example.com/doc/#Upload", - "availability": "Forbidden" + "availability": "Unavailable" } ] } @@ -814,7 +814,7 @@

Documenting a Web API

In the example above the operation that expects an uploaded file became - Forbidden, while the one expecting a comment remains available as + 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 From 5f85c8a9852968b8ec24504ef4ec3b8fb951322d Mon Sep 17 00:00:00 2001 From: alien-mcl Date: Sat, 25 Feb 2023 15:05:20 +0100 Subject: [PATCH 3/5] Revamped whole feature according to code review - or I hope so --- spec/latest/core/core.jsonld | 59 ++++++++++++++++++++++-------------- spec/latest/core/index.html | 41 +++++++++++++------------ 2 files changed, 58 insertions(+), 42 deletions(-) diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index 2669676..8292781 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -28,7 +28,12 @@ "method": "hydra:method", "expects": { "@id": "hydra:expects", "@type": "@vocab" }, "returns": { "@id": "hydra:returns", "@type": "@vocab" }, - "availability": { "@id": "hydra:availability", "@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", @@ -168,27 +173,45 @@ "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:availability", + "@id": "hydra:reason", "@type": "rdf:Property", - "label": "availability", - "comment": "Availability of the operation explicitely stated.", - "range": "hydra:Availability", - "domain": "hydra:Operation", + "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:Availability", + "@id": "hydra:UnavailabilityReason", "@type": "hydra:Class", - "label": "Availability", - "comment": "Availability states when the operation can be invoked.", + "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:Availability", + "@type": "hydra:UnavailabilityReason", "label": "Unavailable", "comment": "States an operation previously announced is unavailable in current circumstances.", "isDefinedBy": "http://www.w3.org/ns/hydra/core", @@ -202,21 +225,13 @@ "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", "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" }, @@ -319,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" @@ -329,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" @@ -339,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 65a6a80..9aff512 100644 --- a/spec/latest/core/index.html +++ b/spec/latest/core/index.html @@ -747,26 +747,27 @@

Documenting a Web API

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 availability predicate that can be added to the Operation - itself. 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. 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.

- -

Usage of the availability is restricted only to the Operations - and MUST NOT be used on SupportedOperations. The availability - predicate also MUST take precedence over a supported operation declaration. - The operation that comes with availability predicate SHOULD be identified + 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:

    -
  • Iri
    • +
  • Iri by using object predicate
  • exact match of a resource described by possibleStatus, method, expects, returns or combination of those.
@@ -801,12 +802,12 @@

Documenting a Web API

"@context": "http://www.w3.org/ns/hydra/context.jsonld", "@id": "http://api.example.com/doc/", "@type": "Collection", - "operation": [ + "retractedOperation": [ { "@type": "Operation", "method": "POST", "expects": "http://api.example.com/doc/#Upload", - "availability": "Unavailable" + "reason": "Unavailable" } ] } From 594c072e48b492713cceda054e29af0c9a57c75d Mon Sep 17 00:00:00 2001 From: alien-mcl Date: Sat, 25 Feb 2023 15:08:54 +0100 Subject: [PATCH 4/5] Fixed formatting issues --- spec/latest/core/core.jsonld | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index 8292781..0fe30d9 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -29,11 +29,11 @@ "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", + "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", @@ -173,24 +173,24 @@ "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", + "@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.", + "@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", From 781693136a4dd94256357a5c261a36258b2cfab5 Mon Sep 17 00:00:00 2001 From: alien-mcl Date: Sat, 4 Nov 2023 19:48:47 +0100 Subject: [PATCH 5/5] Fixed missing JSON commas --- spec/latest/core/core.jsonld | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld index 0fe30d9..5a91e3d 100644 --- a/spec/latest/core/core.jsonld +++ b/spec/latest/core/core.jsonld @@ -182,7 +182,7 @@ "domain": "hydra:Resource", "isDefinedBy": "http://www.w3.org/ns/hydra/core", "vs:term_status": "testing" - } + }, { "@id": "hydra:RetractedOperationSpecification", "@type": "hydra:Class", @@ -190,7 +190,7 @@ "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",