chore: update description of use cases

nmshd · Oct 17, 2023 · 53e1e82 · 53e1e82
1 parent fe4c263
commit 53e1e82
Show file tree

Hide file tree

Showing 28 changed files with 160 additions and 144 deletions.
diff --git a/Gemfile b/Gemfile
@@ -27,11 +27,11 @@ group :jekyll_plugins do
   gem 'jekyll-redirect-from'
 end
 
+gem "tzinfo-data"
 # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
 # and associated library.
 platforms :mingw, :x64_mingw, :mswin, :jruby do
   gem "tzinfo", "~> 1.2"
-  gem "tzinfo-data"
 end
 
 # Performance-booster for watching directories on Windows

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -128,6 +128,8 @@ GEM
       unicode-display_width (~> 1.1, >= 1.1.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    tzinfo-data (1.2023.3)
+      tzinfo (>= 1.0.0)
     unicode-display_width (1.8.0)
     verbal_expressions (0.1.5)
     webrick (1.8.1)

diff --git a/_docs_use-cases/use-case-consumption-accept-incoming-request.md b/_docs_use-cases/use-case-consumption-accept-incoming-request.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/accept-incoming-request
 require:
 required_by:
+api_route_regex: ^PUT /api/v2/Requests/Incoming/{id}/Accept$
 ---
 
 {% include use-cases/use-case-consumption-accept-incoming-request.md %}
diff --git a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/check-if-incoming-request-can-be-accepted
 require:
 required_by:
+api_route_regex: ^put /api/v2/Requests/Incoming/{id}/CanAccept$
 ---
 
 {% include use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md %}
diff --git a/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md b/_docs_use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/check-if-incoming-request-can-be-rejected
 require:
 required_by:
+api_route_regex: ^put /api/v2/Requests/Incoming/{id}/canReject$
 ---
 
 {% include use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md %}
diff --git a/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md b/_docs_use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md
@@ -33,6 +33,7 @@ properties:
 require:
 required_by:
   - /use-case-consumption-create-outgoing-request
+api_route_regex: ^post /api/v2/Requests/Outgoing/Validate$
 ---
 
 {% include use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md %}
diff --git a/_docs_use-cases/use-case-consumption-create-an-attribute.md b/_docs_use-cases/use-case-consumption-create-an-attribute.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/create-an-attribute
 require:
 required_by:
+api_route_regex: ^post /api/v2/Attributes$
 ---
 
 {% include use-cases/use-case-consumption-create-an-attribute.md %}
diff --git a/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md b/_docs_use-cases/use-case-consumption-execute-a-relationshipattributequery.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/execute-a-relationshipattributequery
 require:
 required_by:
+api_route_regex: ^post /api/v2/Attributes/ExecuteRelationshipAttributeQuery$
 ---
 
 {% include use-cases/use-case-consumption-execute-a-relationshipattributequery.md %}
diff --git a/_docs_use-cases/use-case-consumption-execute-a-thirdpartyattributequery.md b/_docs_use-cases/use-case-consumption-execute-a-thirdpartyattributequery.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/execute-a-thirdpartyattributequery
 require:
 required_by:
+api_route_regex: ^post /api/v2/Attributes/executeThirdpartyAttributeQuery$
 ---
 
 {% include use-cases/use-case-consumption-execute-a-thirdpartyattributequery.md %}
diff --git a/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md b/_docs_use-cases/use-case-consumption-execute-an-identityattributequery.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/execute-an-identityattributequery
 require:
 required_by:
+api_route_regex: ^post /api/v2/Attributes/ExecuteIdentityAttributeQuery$
 ---
 
 {% include use-cases/use-case-consumption-execute-an-identityattributequery.md %}
diff --git a/_docs_use-cases/use-case-consumption-get-attribute.md b/_docs_use-cases/use-case-consumption-get-attribute.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/get-attribute
 require:
 required_by:
+api_route_regex: ^get /api/v2/Attributes/{id}$
 ---
 
 {% include use-cases/use-case-consumption-get-attribute.md %}
diff --git a/_docs_use-cases/use-case-consumption-get-incoming-request.md b/_docs_use-cases/use-case-consumption-get-incoming-request.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/get-incoming-request
 require:
 required_by:
+api_route_regex: ^get /api/v2/Requests/Incomming/{id}$
 ---
 
 {% include use-cases/use-case-consumption-get-incoming-request.md %}
diff --git a/_docs_use-cases/use-case-consumption-get-outgoing-request.md b/_docs_use-cases/use-case-consumption-get-outgoing-request.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/get-outgoing-request
 require:
 required_by:
+api_route_regex: ^get /api/v2/Requests/Outgoing/{id}$
 ---
 
 {% include use-cases/use-case-consumption-get-outgoing-request.md %}
diff --git a/_docs_use-cases/use-case-consumption-query-attributes.md b/_docs_use-cases/use-case-consumption-query-attributes.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/query-attributes
 require:
 required_by:
+api_route_regex: ^get /api/v2/Attributes$
 ---
 
 {% include use-cases/use-case-consumption-query-attributes.md %}
diff --git a/_docs_use-cases/use-case-consumption-query-incoming-requests.md b/_docs_use-cases/use-case-consumption-query-incoming-requests.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/query-incoming-requests
 require:
 required_by:
+api_route_regex: ^get /api/v2/Requests/Incomming$
 ---
 
 {% include use-cases/use-case-consumption-query-incoming-requests.md %}
diff --git a/_docs_use-cases/use-case-consumption-query-outgoing-requests.md b/_docs_use-cases/use-case-consumption-query-outgoing-requests.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/query-outgoing-requests
 require:
 required_by:
+api_route_regex: ^get /api/v2/Requests/Outgoing$
 ---
 
 {% include use-cases/use-case-consumption-query-outgoing-requests.md %}
diff --git a/_docs_use-cases/use-case-consumption-reject-incoming-request.md b/_docs_use-cases/use-case-consumption-reject-incoming-request.md
@@ -32,6 +32,7 @@ properties:
   - link: consumption/reject-incoming-request
 require:
 required_by:
+api_route_regex: ^get /api/v2/Requests/Outgoing/{id}/Reject$
 ---
 
 {% include use-cases/use-case-consumption-reject-incoming-request.md %}
diff --git a/_includes/use-cases/use-case-consumption-accept-incoming-request.md b/_includes/use-cases/use-case-consumption-accept-incoming-request.md
@@ -1,18 +1,23 @@
-Attempts to accept an incoming request by it's Id.
+{{properties.description}}
 
-A [request](/integrate/data-model-overview#request) consists of [RequestItems](/integrate/data-model-overview#requestitem)
-and/or [RequestItemGroups](/integrate/data-model-overview#requestitemgroup). To accept the request
-the body has to contain a items array that indicates the decisions made for each request item.
-The decision are expressed through [ResponseItems](/integrate/data-model-overview#responseitem) whose
-structure is dependent on the corresponding RequestItem.
+{% include properties_list.html %}
 
-## Example Body
+This use-case attempts to accept an incomming [Request](/integrate/data-model-overview#request). 
+It is advised to [check if incoming request can be accepted](/use-case-consumption-check-if-incoming-request-can-be-accepted)
+in advance.
 
-```json
-{
-  "items": [{ "accept": true }, { "accept": false }]
-}
-```
+## Parameters
 
-{% include rapidoc api_route_regex="^put /api/v2/Requests/Incoming/{id}/Accept$" title="API docs" %}
+- The `id` of the incomming request.
+- The decision for each individual [RequestItem](/integrate/data-model-overview#request)
+expressed as the appropriate [Parameters defined in the Data Model](/integrate/requests-and-requestitems).
 
+## On Success
+
+- The request is processed according to the decisions made. 
+- The sending peer is informed about your decisions. 
+
+## On Failure
+
+- The decisions do not match the request items.
+- An item that has the mustBeAccepted field set was declined.
diff --git a/...des/use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md b/...des/use-cases/use-case-consumption-check-if-incoming-request-can-be-accepted.md
@@ -1,18 +1,21 @@
-Checks if an incoming request can be successfully accepted.
+{{properties.description}}
 
-A [request](/integrate/data-model-overview#request) consists of [RequestItems](/integrate/data-model-overview#requestitem)
-and/or [RequestItemGroups](/integrate/data-model-overview#requestitemgroup). To accept the request
-the body has to contain a items array that indicates the decisions made for each request item.
-The decision are expressed through [ResponseItems](/integrate/data-model-overview#responseitem) whose
-structure is dependent on the corresponding RequestItem.
+{% include properties_list.html %}
 
-## Example Body
+This use-case tests if an incomming [Request](/integrate/data-model-overview#request)
+can be accepted with the given parameters without actually accepting it.
 
-```json
-{
-  "items": [{ "accept": true }, { "accept": false }]
-}
-```
+## Parameters
 
-{% include rapidoc api_route_regex="^put /api/v2/Requests/Incoming/{id}/CanAccept$" title="API docs" %}
+- The `id` of the incomming request.
+- The decision for each individual [RequestItem](/integrate/data-model-overview#request)
+expressed as the appropriate [Parameters defined in the Data Model](/integrate/requests-and-requestitems).
 
+## On Success 
+
+- The request can be accepted with the given parameters.
+
+## On Failure
+
+- The request can not be accepted.
+- A detailed error describes the problem.
diff --git a/...des/use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md b/...des/use-cases/use-case-consumption-check-if-incoming-request-can-be-rejected.md
@@ -1,18 +1,21 @@
-Checks if an incoming request can be successfully rejected.
+{{properties.description}}
 
-A [request](/integrate/data-model-overview#request) consists of [RequestItems](/integrate/data-model-overview#requestitem)
-and/or [RequestItemGroups](/integrate/data-model-overview#requestitemgroup). To reject the request
-the body has to contain a items array that indicates the decisions made for each request item.
-The decision are expressed through [ResponseItems](/integrate/data-model-overview#responseitem) whose
-structure is dependent on the corresponding RequestItem.
+{% include properties_list.html %}
 
-## Example Body
+This use-case tests if an incomming [Request](/integrate/data-model-overview#request)
+can be rejected with the given parameters without actually rejecting it.
 
-```json
-{
-  "items": [{ "accept": false }, { "accept": false }]
-}
-```
+## Parameters
 
-{% include rapidoc api_route_regex="^put /api/v2/Requests/Incoming/{id}/CanReject$" title="API docs" %}
+- The `id` of the incomming request.
+- The decision for each individual [RequestItem](/integrate/data-model-overview#request)
+expressed as the appropriate [Parameters defined in the Data Model](/integrate/requests-and-requestitems).
 
+## On Success 
+
+- The request can be requected with the given parameters.
+
+## On Failure
+
+- The request can not be rejected with the given parameters.
+- A detailed error describes the problem.
diff --git a/...udes/use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md b/...udes/use-cases/use-case-consumption-check-if-outgoing-request-can-be-created.md
@@ -1,34 +1,21 @@
-Validates an outgoing request without creating it.
+{{properties.description}}
 
 {% include properties_list.html %}
 
-The content is the to be created request defined in the [data model](/integrate/data-model-overview#request).
+This use-case is intended to check if a [LocalRequest](integrate/data-model-overview#localrequest) can be created
+based on a given `request` (as a [Request](integrate/data-model-overview#localrequest) datastructure) for a given `peer`.
 
-## Example Body
+## Parameters
 
-```json
-{
-  "content": {
-    "expiresAt": "2024-01-01T00:00:00.000Z",
-    "items": [
-      {
-        "@type": "ShareAttributeRequestItem",
-        "mustBeAccepted": true,
-        "attribute": {
-          "@type": "IdentityAttribute",
-          "owner": "",
-          "value": {
-            "@type": "DisplayName",
-            "value": "Example"
-          }
-        },
-        "sourceAttributeId": "<id of attribute above, generated on creation>"
-      }
-    ]
-  },
-  "peer": "peerId"
-}
-```
+- The `content` for the to be created request is described in the [data model](integrate/data-model-overview#request).
+- The `peer` is the address of the recipient of this request. There can only be one peer per request.
 
-{% include rapidoc api_route_regex="^post /api/v2/Requests/Outgoing/Validate$" title="API docs" %}
+## On Success
+ Please [check if the outgoing request can be created](use-case-consumption-check-if-outgoing-request-can-be-created) for more details.
+- A [LocalRequest](integrate/data-model-overview#localrequest) for the given parameters can be created.
 
+## On Failure
+
+- The request cannot be created if the peer is unknown.
+- The request cannot be created if the request content is malformed.
+- The response contains a detailed error message.
diff --git a/_includes/use-cases/use-case-consumption-create-an-attribute.md b/_includes/use-cases/use-case-consumption-create-an-attribute.md
@@ -1,22 +1,19 @@
-Create an attribute.
+{{properties.description}}
 
-The content is the to be created attribute, either an 'IdentityAttribute' or an
-'RelationshipAttribute', defined in the [data model](/integrate/data-model-overview#attributes).
+{% include properties_list.html %}
 
-## Example Body
+This use-case is intended to create an [LocalAttribute](/integrate/data-model-overview#localattribute)
+based on a given `attribute` (as a [Attribute](/integrate/data-model-overview#attributes) datastructure).
 
-```json
-{
-  "content": {
-    "@type": "IdentityAttribute",
-    "owner": "<your address>",
-    "value": {
-      "@type": "DisplayName",
-      "value": "Example"
-    }
-  }
-}
-```
+## Parameters 
 
-{% include rapidoc api_route_regex="^post /api/v2/Attributes$" %}
+- The `content` for the to be created attribute is described in the [data model](/integrate/data-model-overview#attributes)
 
+## On Success 
+
+- A [LocalAttribute](/integrate/data-model-overview#localattribute) is created according to the paramter.
+
+## On Failure
+
+- The attribute cannot be created if the parameter is malformed.
+
diff --git a/_includes/use-cases/use-case-consumption-create-outgoing-request.md b/_includes/use-cases/use-case-consumption-create-outgoing-request.md
@@ -2,7 +2,8 @@
 
 {% include properties_list.html %}
 
-This use-case is intended to create an actionable [LocalRequest](integrate/data-model-overview#localrequest) based on a given `request` (as a [Request](integrate/data-model-overview#localrequest) datastructure) for a given `peer`. One can (and should) [check if the outgoing request can be created](use-case-consumption-check-if-outgoing-request-can-be-created) before creating the request with this use-case.
+This use-case is intended to create an actionable [LocalRequest](integrate/data-model-overview#localrequest) based on a given `request` (as a [Request](integrate/data-model-overview#localrequest) datastructure) for a given `peer`.
+One can (and should) [check if the outgoing request can be created](use-case-consumption-check-if-outgoing-request-can-be-created) before creating the request with this use-case.
 
 ## Parameters
 

diff --git a/_includes/use-cases/use-case-consumption-execute-a-relationshipattributequery.md b/_includes/use-cases/use-case-consumption-execute-a-relationshipattributequery.md
@@ -1,28 +1,18 @@
-Execute relationship attribute query.
-
-[Relationship attributes](/integrate/data-model-overview#relationshipattribute) are all attributes that are shared within a
-relationship of the identity. This endpoint is used to query the realationship attributes of a peer.
-
-The structure of the query is defined in the [data model](/integrate/data-model-overview#attributequeries).
-
-## Example Body
-
-```json
-{
-  "query": {
-    "key": "ElectricMeterNumber",
-    "owner": "enmeshedAddressOfOwner",
-    "attributeCreationHints": {
-      "confidentiality": "public",
-      "title": "electric meter number",
-      "valueType": "ProprietaryString",
-      "valueHints": {
-        "@type": "Proprietary"
-      }
-    }
-  }
-}
-```
-
-{% include rapidoc api_route_regex="^post /api/v2/attributes/ExecuteRelationshipAttributeQuery$" title="API docs" %}
+{{properties.description}}
 
+{% include properties_list.html %}
+
+This use-case is intended to query a peer's [relationship attributes](/integrate/data-model-overview#relationshipattribute).
+
+## Parameters
+
+- The `query` for the searched relationship attribute is described in the [data model](/integrate/data-model-overview#relationshipattributequery).
+
+## On Success
+
+- Returns the relationship attribute that matches the query.
+
+## On Failure
+
+- No corresponding attributes could be found.
+- The query was malformed. Please make sure it complies to the [data model](/integrate/data-model-overview#relationshipattributequery).