Corrections in basic-metadata.md and added changes to ditto-api-2.yml…

…-Swagger Doc.

Signed-off-by: julian <[email protected]>

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -403,6 +403,7 @@ paths:
         - $ref: '#/components/parameters/thingIdPathParam'
         - $ref: '#/components/parameters/ifMatchHeaderParam'
         - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
+        - $ref: '#/components/parameters/putMetadataParam'
         - $ref: '#/components/parameters/requestedAcksParam'
         - $ref: '#/components/parameters/timeoutParam'
         - $ref: '#/components/parameters/responseRequiredParam'
@@ -4664,6 +4665,10 @@ components:
           description: |-
             _(read-only)_ The modified timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on each
             modification of a Thing. This field is not returned by default but must be selected explicitly.
+        _metadata:
+          type: string
+          description: |-
+            _(read-only)_ The Metadata of the Thing will be included in the Thing. This field is not returned by default but must be selected explicitly.
     Policy:
       type: object
       description: policy consisting of policy entries
@@ -4858,6 +4863,14 @@ components:
       required: false
       schema:
         type: string
+    putMetadataParam:
+      name: Put-Metadata
+      in: header
+      description:  >-
+        The `put-metadata` header, which sets Metadata information in the Thing.
+      required: false
+      schema:
+        type: string
     featureIdPathPathParam:
       name: featureId
       in: path

documentation/src/main/resources/pages/ditto/basic-metadata.md

@@ -13,17 +13,21 @@ Metadata can be manipulated by using the `metadata` header, see [here](protocol-
 
 ## Predefined Metadata 
 
+Currently, there are no pre-defined Metadata keys.
+
+<!--
 Right now, the only fixed pre-defined Metadata key is `issuedAt`.
 
 ### The `issuedAt` Metadata key
  
 The Metadata key `issuedAt` describes the timestamp when the current value of a feature property was _recorded_ (_not when it was set_).
 This means, that a client _can_ send this value by using the `metadata` header. If the client does not send
 this header the `issuedAt` field will be set by Ditto with the timestamp when the value was written.
+-->
 
 ## Setting custom Metadata
 
-The only way to set arbitrary `Metadata` is by using the `metadata` header, see [here](protocol-specification.html#headers) for more information.
+The only way to set arbitrary `Metadata` is by using the `put-metadata` header, see [here](protocol-specification.html#headers) for more information.
 The Format of the Json Array is 
 
 ```
@@ -33,8 +37,8 @@ The Format of the Json Array is
     "value":{"issuedAt":someTimestamp,"issuedBy":{"name":"me","mail":"[email protected]"}}
   },
   {
-    "key":"*/",
-    "value":{"foo": bar"}
+    "key":"*/foo",
+    "value": "bar"
   },
   ...
 ]
@@ -43,16 +47,36 @@ The Format of the Json Array is
 where `key` describes the hierarchical position in the Thing where the metadata is placed and 
 `value` is a map of Metadata keys to their respective values.
 
-A special Syntax for the key is `*/` which means that all affected Json Leafs of the Modify Operation will
-get the Metadata Key `foo` with value `bar`. So if, for example, only the affected Json Leafes should 
+A special Syntax for the key is `*/{key}` which means that all affected Json Leafs of the Modify Operation will
+get the Metadata Key `{key}` with the given value. So if, for example, only the affected Json Leafes should 
 get the timestamp where the changed values were recorded, one would set the `metadata` header as shown in the
 following example: 
 
 ```json
 [
   {
-    "key":"*/",
-    "value":{"issuedAt": someTimestamp }
+    "key":"*/timestamp",
+    "value": someTimestamp
   }
 ]
 ```
+
+## Reading Metadata Information
+
+Currently, the only way to retrieve stored Metadata is by a full thing query, e.g. via the [HTTP API](http-api-doc.html).
+But, `get-metadata` has to be added to the queried fields together with `thingId,attributes,_metadata`.
+
+For example a `GET` request to `https://{ditto-instance}/api/2/things/{namespace}:{thing}?fields=thingId,attributes,_metadata`
+will yield the Metadata stored for the given Thing, in the following format:
+
+```json
+{
+    "thingId": ...,
+    "attributes": {
+        ...
+    },
+    "_metadata": {
+        ...
+    }
+}
+``` 

documentation/src/main/resources/pages/ditto/protocol-specification.md

@@ -98,7 +98,7 @@ HTTP protocol, for example the prefix `ditto-*`.
 The interaction between the headers `response-required`, `requested-acks` and `timeout` is documented
 [here](basic-acknowledgements.html#interaction-between-headers).
 
-More information of the Metadata management of Ditto and predefined Metadata can be found [here](basic-metadata.html).
+More information of the Metadata management of Ditto and predefined Metadata-Keys can be found [here](basic-metadata.html).
 
 ## Path