Add HTTP and CoAP mapping draft

Author: martinjaeger

docs/.vuepress/config.js

@@ -55,6 +55,13 @@ module.exports = {
                     '3b_can',
                     '3c_lora'
                 ]
+            },{
+                title: 'Protocol Mapping',
+                collapsable: false,
+                children: [
+                    '4a_http',
+                    '4b_coap'
+                ]
             }],
             '/v0.2/': [{
                 title: 'Why ThingSet?',

docs/4a_http.md

@@ -0,0 +1,24 @@
+---
+title: "HTTP"
+---
+
+# ThingSet to HTTP mapping
+
+::: warning
+This part of the protocol specification is still work in progress.
+:::
+
+## Key concepts
+
+ThingSet is developed for point-to-point connections or small local networks, but the protocol functions were developed such that they can be easily integrated into larger networks or the internet using an HTTP gateway.
+
+Many web applications interact using JSON APIs (sometimes in a RESTful way), so the compatibility with JSON web APIs is an important feature of the ThingSet protocol.
+
+In order to reduce the complexity of the protocol, the features offered by HTTP were reduced:
+
+- Convention over configuration
+    - Only two content-types JSON and CBOR are supported. They are detected automatically and no content-type header is needed.
+    - Predefined URI layout matching the data structure.
+    - Unit of data objects stored in the name (key) of a map, so the required amount of nesting in the JSON data structure is limited to categories only.
+
+The response codes of ThingSet are aligned with CoAP and thus also allow a simple translation to HTTP. The main difference is that HTTP doesn't allow to indicate successful requests as fine-grained as CoAP, so the status will be mostly 200 OK or 204 No Content.

docs/4b_coap.md

@@ -0,0 +1,24 @@
+---
+title: "CoAP"
+---
+
+# ThingSet to CoAP mapping
+
+::: warning
+This part of the protocol specification is still work in progress.
+:::
+
+## Key concepts
+
+ThingSet uses only a subset of CoAPs features in order to make it more simple and compact:
+
+- Mapping to CoAP message types:
+    - ThingSet requests are always CON
+    - Only publication messages are NON
+    - No dedicated ACK, the response must also contain data (only piggybacked responses)
+    - RST needed? probably not...
+- No message IDs: Synchronous communication necessary
+- PUT request is not supported. Use POST to create a resource and iPATCH to update it.
+- PATCH requests are always idempotent, i.e. only iPATCH is supported
+
+The binary function codes of ThingSet are the same as CoAP method codes. The status codes are also aligned, but contain an offset as explained before.