add documentation about live channel to http docu;

Signed-off-by: Stefan Maute <stefan.maute@bosch.io>

documentation/src/main/resources/pages/ditto/httpapi-concepts.md

@@ -62,7 +62,7 @@ This maps to the following HTTP API endpoints:
 
 #### `/things` in API 2 - dynamic part
 
-Additionally to that "static part" of the HTTP API which is defined by Ditto, the API is dynamically enhanced by the
+Additionally, to that "static part" of the HTTP API which is defined by Ditto, the API is dynamically enhanced by the
 JSON structure of the Thing.<br/>
 
 {% include note.html content="This automatically turns each small aspect of a **digital twin** into an API endpoint." %}
@@ -140,7 +140,7 @@ This maps to the following HTTP API endpoints:
 
 ## Partial updates
 
-As a benefit of the above mentioned mechanism that an API is automatically available based on the JSON structure, the
+As a benefit of the above-mentioned mechanism that an API is automatically available based on the JSON structure, the
 "partial update" pattern can be applied when modifying data.
 
 The benefit of this is a reduction in payload to be transferred. Further, it is beneficial because other parts of the

documentation/src/main/resources/pages/ditto/httpapi-overview.md

@@ -17,6 +17,24 @@ It however tries to follow the other best practices.
 
 If you have any feedback on how to improve at that point, Ditto's developer team is [eager to learn](feedback.html).
 
+## Channel
+
+Ditto supports two types of communication channels: `twin` and `live`. 
+
+The `twin` channel is used to communicate with the **digital twin** representation of a device.
+The `live` channel can be used to communicate directly with an actual device. 
+In case the `live` channel is used, the device itself is responsible for answering the command/message.   
+If no response is returned the request will result in a timeout and Ditto will respond with `408 Request Timeout`.
+This timeout can be set with the `timeout` parameter. If no `timeout` parameter is set the default of `10s` is used to
+wait for response of the device.
+When routing live commands to devices Ditto is doing an [authorization check](basic-auth.html) based on the policy
+of the thing. Ditto also filters responses based on that policy. 
+
+The default channel for all HTTP requests is the `twin` channel. The channel can either be set via HTTP header or via
+query parameter.
+
+For more information about the channel concept can be found [here](protocol-twinlive.html).  
+
 ## Content Type
 
 Currently, the content-type `application/json` is supported for all REST resources except the _PATCH_ resource.

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

@@ -124,7 +124,7 @@ The JSON value to apply at the specified path.
 
 ## Status
 
-Some protocol messages (for example **responses**) contain a HTTP status code which is stored in this field.
+Some protocol messages (for example **responses**) contain an HTTP status code which is stored in this field.
 
 ## Extra
 

gateway/service/src/main/java/org/eclipse/ditto/gateway/service/endpoints/routes/things/MessagesRoute.java

@@ -356,7 +356,8 @@ private static MessageBuilder<Object> createMessageBuilderWithoutPayload(final M
         return MessagesModelFactory.newMessageBuilder(headers);
     }
 
-    private static MessageBuilder<Object> createMessageBuilderWithPayload(final ByteBuffer payload, final ContentType contentType,  final MessageHeaders headers) {
+    private static MessageBuilder<Object> createMessageBuilderWithPayload(final ByteBuffer payload,
+            final ContentType contentType,  final MessageHeaders headers) {
         final ByteBuffer payloadWithoutOffset = ByteBuffer.wrap(payload.array());
 
         MessageCommandSizeValidator.getInstance().ensureValidSize(() ->
@@ -417,8 +418,8 @@ private Duration checkClaimTimeout(final Duration timeout) {
      * it's dangerous to rely on the (non-)existence of a content-length" (see {@link RequestEntity#getContentLengthOption()}).
      *
      * @param request The request.
-     * @return {@code true} if the message contains Content-Length {@code 0}; {@code false} if no Content-Length is found or
-     * it isn't {@code 0}.
+     * @return {@code true} if the message contains Content-Length {@code 0}; {@code false} if no Content-Length is
+     * found or it isn't {@code 0}.
      * @see RequestEntity#getContentLengthOption()
      */
     private static boolean hasZeroContentLength(final HttpRequest request) {