re-structure the connectivity section

* moved protocol bindings in there
* moved websocket binding into httpapi section
* adjusted arc image
* fixed broken links

Signed-off-by: Thomas Jaeckle <thomas.jaeckle@bosch-si.com>

documentation/src/main/resources/_data/sidebars/ditto_sidebar.yml

@@ -157,6 +157,9 @@ entries:
     - title: Messages
       url: /httpapi-messages.html
       output: web
+    - title: WebSocket protocol binding
+      url: /httpapi-protocol-bindings-websocket.html
+      output: web
     - title: Server sent events
       url: /httpapi-sse.html
       output: web
@@ -170,9 +173,18 @@ entries:
     - title: Overview
       url: /connectivity-overview.html
       output: web
-    - title: Payload Mapping
+    - title: Payload mapping
       url: /connectivity-mapping.html
       output: web
+    - title: Manage connections
+      url: /connectivity-manage-connections.html
+      output: web
+    - title: AMQP 0.9.1 protocol binding
+      url: /connectivity-protocol-bindings-amqp091.html
+      output: web
+    - title: AMQP 1.0 protocol binding
+      url: /connectivity-protocol-bindings-amqp10.html
+      output: web
 
   - title: Ditto Protocol
     output: web
@@ -224,15 +236,6 @@ entries:
     - title: Bindings
       url: /protocol-bindings.html
       output: web
-    - title: → Websocket Binding
-      url: /protocol-bindings-websocket.html
-      output: web
-    - title: → AMQP 0.9.1 Binding
-      url: /protocol-bindings-amqp091.html
-      output: web
-    - title: → AMQP 1.0 Binding
-      url: /protocol-bindings-amqp10.html
-      output: web
 
     - title: Examples
       url: /protocol-examples.html

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

@@ -21,8 +21,9 @@ The components have the following tasks:
 * [Things-Search](architecture-services-things-search.html): tracking changes to `Things`, `Features`, `Policies` and 
   updating an optimized search index + executes queries on this search index
 * [Gateway](architecture-services-gateway.html): provides HTTP and WebSocket API and orchestrates the backing persistence services
-* [Connectivity](architecture-services-connectivity.html): connects to an AMQP 1.0 endpoint (e.g. [Eclipse Hono](https://eclipse.org/hono/)) 
-  and consumes messages in [Ditto Protocol](protocol-overview.html) from it
+* [Connectivity](architecture-services-connectivity.html): connects to AMQP 1.0 endpoints (e.g. [Eclipse Hono](https://eclipse.org/hono/))
+  or AMQP 0.9.1 endpoints (e.g. RabbitMQ) and consumes messages in [Ditto Protocol](protocol-overview.html) from it or transforms
+  messages into Ditto Protocol
 
 ## Components
 

documentation/src/main/resources/pages/ditto/architecture-services-connectivity.md

@@ -9,7 +9,7 @@ permalink: architecture-services-connectivity.html
   {%
     include note.html content="In Ditto 0.1.0-M2 the AMQP-Bridge service was added with the goal to be able to establish connections to 
                                 [Eclipse Hono](https://eclipse.org/hono/) as well as other [AMQP 1.0] endpoints. 
-                                With Ditto [TODO: release tag] the AMQP-Bridge architecture became more modular and extensible to support additional 
+                                With Ditto 0.3.0-M1 the AMQP-Bridge architecture became more modular and extensible to support additional 
                                 protocols beside [AMQP 1.0]. Therefore it was renamed to connectivity service."
   %}
 
@@ -40,7 +40,7 @@ Other services can communicate with the connectivity service via:
 ## Persistence
 
 The connectivity service uses [Akka persistence](https://doc.akka.io/docs/akka/current/persistence.html?language=java) and 
-with that [Event sourcing](http://localhost:4000/basic-signals.html#architectural-style) in order to persist changes 
+with that [Event sourcing](basic-signals.html#architectural-style) in order to persist changes 
 and restore persisted entities.
 
 ## Tasks
@@ -56,8 +56,8 @@ and restore persisted entities.
 
 
 
-[AMQP 1.0]: protocol-bindings-amqp10.html
+[AMQP 1.0]: connectivity-protocol-bindings-amqp10.html
 [Ditto Protocol]: protocol-overview.html
 [Ditto Protocol Message]: protocol-specification-things-messages.html
 [payload mapping]: protocol-specification-things-messages.html
-[Protocol Bindings]: protocol-bindings.html
+[Protocol Bindings]: protocol-bindings.html

documentation/src/main/resources/pages/ditto/architecture-services-gateway.md

@@ -6,7 +6,7 @@ permalink: architecture-services-gateway.html
 ---
 
 The "gateway" service is responsible for providing Ditto's [HTTP](httpapi-overview.html) + 
-[WebSocket](protocol-bindings-websocket.html) API and **orchestrating** the backing persistence services.
+[WebSocket](httpapi-protocol-bindings-websocket.html) API and **orchestrating** the backing persistence services.
 
 ## Model
 
@@ -24,8 +24,8 @@ The gateway service has no persistence by its own.
 
 * translate HTTP request to [commands](basic-signals-command.html) and translates [command responses](basic-signals-commandresponse.html)
   back to HTTP responses
-* translate [Ditto Protocol](protocol-overview.html) messages incoming via the [WebSocket](protocol-bindings-websocket.html)
+* translate [Ditto Protocol](protocol-overview.html) messages incoming via the [WebSocket](httpapi-protocol-bindings-websocket.html)
   to [commands](basic-signals-command.html) and translates [command responses](basic-signals-commandresponse.html) back
   to [Ditto Protocol](protocol-overview.html) response messages
 * subscribe for [events](basic-signals-event.html) in Ditto cluster and emits [change notifications](basic-changenotifications.html)
-  via connected [WebSocket](protocol-bindings-websocket.html) clients or via [SSEs](httpapi-sse.html)
+  via connected [WebSocket](httpapi-protocol-bindings-websocket.html) clients or via [SSEs](httpapi-sse.html)

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

@@ -9,7 +9,7 @@ Ditto provides two ways to interact with:
 
 * A [REST-like HTTP API](httpapi-overview.html) with a sophisticated resource layout that allows to create, read,
   update and delete Things and the Thing's data.
-* A JSON-based [WebSocket API](protocol-bindings-websocket.html) implementing the
+* A JSON-based [WebSocket API](httpapi-protocol-bindings-websocket.html) implementing the
   [Ditto Protocol](protocol-overview.html).
 
 

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

@@ -9,7 +9,7 @@ permalink: basic-changenotifications.html
 Events are emitted after an entity (either a **Digital Twin** or an actual device) was changed.
 
 At the Ditto API there are two ways for getting notified of such events:
-* Via the [WebSocket API](protocol-bindings-websocket.html) a WebSocket client gets all Events the authenticated subject
+* Via the [WebSocket API](httpapi-protocol-bindings-websocket.html) a WebSocket client gets all Events the authenticated subject
   (e.g. a user) is [authorized](basic-auth.html) to receive as [Ditto Protocol](protocol-overview.html) messages.
 * Via [HTTP SSEs](httpapi-sse.html) a consumer of the SSE `EventSource` gets all Events the authenticated subject
   (e.g. a user) is [authorized](basic-auth.html) to receive directly in the format of the changed entity 

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

@@ -31,7 +31,7 @@ Eclipse Ditto is not a message broker and does not want to offer features a mess
 
 It can be seen as a message router which:
 * accepts messages via 2 APIs ([HTTP](httpapi-messages.html) and 
-  [Ditto Protocol](protocol-specification-things-messages.html), e.g. via [WebSocket binding](protocol-bindings-websocket.html))
+  [Ditto Protocol](protocol-specification-things-messages.html), e.g. via [WebSocket binding](httpapi-protocol-bindings-websocket.html))
 * checks for **currently connected** interested parties whether they may receive a specific Message 
   (performs [authorization checks](basic-auth.html#authorization))
 * routes the Message and reply Messages in between connected clients 
@@ -73,11 +73,11 @@ content-type and serialization is arbitrary.
 ## APIs
 
 Messages can be sent via
-* the [WebSocket API](protocol-bindings-websocket.html) as [Ditto Protocol](protocol-overview.html) messages,
+* the [WebSocket API](httpapi-protocol-bindings-websocket.html) as [Ditto Protocol](protocol-overview.html) messages,
 * the [HTTP API](httpapi-overview.html) either as "fire and forget" messages or, when expecting a response, in a
   blocking way at the [Messages HTTP API endpoint](http-api-doc.html#/Messages)
 
-Messages can, however, be received only via the [WebSocket API](protocol-bindings-websocket.html) as
+Messages can, however, be received only via the [WebSocket API](httpapi-protocol-bindings-websocket.html) as
 [Ditto Protocol](protocol-overview.html) messages.
 
 

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

@@ -20,7 +20,7 @@ No custom indexes have to be defined as the structure in the database is "flatte
 ## Search queries
 
 Queries can be made via Ditto's APIs ([HTTP](httpapi-search.html) or 
-[Ditto Protocol](protocol-specification-things-search.html) e.g. via [WebSocket](protocol-bindings-websocket.html)).
+[Ditto Protocol](protocol-specification-things-search.html) e.g. via [WebSocket](httpapi-protocol-bindings-websocket.html)).
 
 **Example:** Search for all things located in "living-room", reorder the list to start with the lowest thing ID as the first element, 
 and return the first 5 results:

documentation/src/main/resources/pages/ditto/basic-signals-event.md

@@ -12,5 +12,5 @@ Events are one of the centerpieces of Ditto:
 * they are persisted/appended into the data store,
 * they are published in the Ditto cluster, so other Ditto back end services can react on them (e.g. in order to update
   the search index) and
-* they are published to interested and authorized parties via the [WebSocket API](protocol-bindings-websocket.html) as
+* they are published to interested and authorized parties via the [WebSocket API](httpapi-protocol-bindings-websocket.html) as
   well as via [HTTP Server Sent Events](httpapi-sse.html) as [change notifications](basic-changenotifications.html).

documentation/src/main/resources/pages/ditto/connectivity-manage-connections.md

@@ -0,0 +1,52 @@
+---
+title: Manage connections in connectivity
+keywords: 
+tags: [connectivity]
+permalink: connectivity-manage-connections.html
+---
+
+In order to manage (CRUD) connections in Ditto [DevOps commands](installation-operating.html#connectivity-service-commands)
+have to be used. There is no separate HTTP API for managing the connections as this is not a task for a developer using 
+the digital twin APIs but more for a "devops engineer" creating new connections to external systems very seldom.
+
+TODO move the example from the DevOps commands page to here - only describe the concept of piggyback commands there.
+
+## CRUD commands
+
+The following commands are available in order to manage connections:
+* [create](#create-connection)
+* [retrieve](#retrieve-connection)
+* [delete](#delete-connection)
+
+A "modify" is currently not available, use delete + create in order to modify existing connections.
+
+### Create connection
+
+TODO describe command
+
+### Retrieve connection
+
+TODO describe command
+
+### Delete connection
+
+TODO describe command
+
+## Helper commands
+
+The following commands are available in help creating connections + retrieve the status of existing connections:
+* [test](#test-connection)
+* [retrieve desired connection status](#retrieve-connection-status)
+* [retrieve actual connection status + metrics](#retrieve-connection-metrics)
+
+### Test connection
+
+TODO describe command
+
+### Retrieve connection status
+
+TODO describe command
+
+### Retrieve connection metrics
+
+TODO describe command

documentation/src/main/resources/pages/ditto/connectivity-mapping.md

@@ -1,5 +1,5 @@
 ---
-title: Payload mapping
+title: Payload mapping in connectivity
 keywords: mapping, transformation, payload, javascript
 tags: [connectivity]
 permalink: connectivity-mapping.html

documentation/src/main/resources/pages/ditto/protocol-bindings-amqp091.md → documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp091.md

@@ -1,39 +1,39 @@
 ---
 title: AMQP 0.9.1 protocol binding
-keywords: binding, protocol, amqp, amqp10
-tags: [protocol]
-permalink: protocol-bindings-amqp091.html
+keywords: binding, protocol, amqp, amqp091, rabbitmq
+tags: [protocol, connectivity]
+permalink: connectivity-protocol-bindings-amqp091.html
 ---
 
-The Ditto Protocol message can be sent *as is* as **AMQP 1.0** message.
+The Ditto Protocol message can be sent *as is* as **AMQP 0.9.1** message.
 The Ditto Protocol JSON must be sent as `UTF-8` encoded String payload.
 
-The `content-type` of AMQP 1.0 messages must be set to:
+The `content-type` of AMQP 0.9.1 messages must be set to:
 
 ```
 application/vnd.eclipse.ditto+json
 ```
 
-## AMQP 1.0 properties
+## AMQP 0.9.1 properties
 
-Supported AMQP 1.0 properties which are interpreted in a specific way are:
+Supported AMQP 0.9.1 properties which are interpreted in a specific way are:
 
 * `content-type`: for defining the Ditto Protocol content-type
 * `correlation-id`: for correlating request messages to responses
 
 
-## Establishing connecting to an AMQP 1.0 endpoint
+## Establishing connecting to an AMQP 0.9.1 endpoint
 
 Ditto's [Connectivity service](architecture-services-connectivity.html) is responsible for creating new and managing 
 existing connections.
 
 This can be done dynamically at runtime without the need to restart any microservice using a
-[Ditto operations command](installation-operating.html#create-a-new-amqp-bridge-connection).
+[Ditto operations command](installation-operating.html#connectivity-service-commands).
 
 
 ## Messages
 
-Messages consumed via the AMQP 1.0 binding are treated similar to the [WebSocket binding](protocol-bindings-websocket.html)
+Messages consumed via the AMQP 1.0 binding are treated similar to the [WebSocket binding](httpapi-protocol-bindings-websocket.html)
 meaning that the messages are expected to be [Ditto Protocol](protocol-overview.html) messages serialized as JSON (as 
 shown for example in the [protocol examples](protocol-examples.html)).
 

documentation/src/main/resources/pages/ditto/protocol-bindings-amqp10.md → documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp10.md

@@ -1,8 +1,8 @@
 ---
 title: AMQP 1.0 protocol binding
 keywords: binding, protocol, amqp, amqp10
-tags: [protocol]
-permalink: protocol-bindings-amqp10.html
+tags: [protocol, connectivity]
+permalink: connectivity-protocol-bindings-amqp10.html
 ---
 
 The Ditto Protocol message can be sent *as is* as **AMQP 1.0** message.
@@ -28,12 +28,12 @@ Ditto's [Connectivity service](architecture-services-connectivity.html) is respo
 existing connections.
 
 This can be done dynamically at runtime without the need to restart any microservice using a
-[Ditto operations command](installation-operating.html#create-a-new-amqp-bridge-connection).
+[Ditto operations command](installation-operating.html#connectivity-service-commands).
 
 
 ## Messages
 
-Messages consumed via the AMQP 1.0 binding are treated similar to the [WebSocket binding](protocol-bindings-websocket.html)
+Messages consumed via the AMQP 1.0 binding are treated similar to the [WebSocket binding](httpapi-protocol-bindings-websocket.html)
 meaning that the messages are expected to be [Ditto Protocol](protocol-overview.html) messages serialized as JSON (as 
 shown for example in the [protocol examples](protocol-examples.html)).
 

documentation/src/main/resources/pages/ditto/protocol-bindings-websocket.md → documentation/src/main/resources/pages/ditto/httpapi-protocol-bindings-websocket.md

@@ -1,11 +1,11 @@
 ---
 title: WebSocket protocol binding
-keywords: binding, protocol, websocket
-tags: [protocol]
-permalink: protocol-bindings-websocket.html
+keywords: binding, protocol, websocket, http
+tags: [protocol, http]
+permalink: httpapi-protocol-bindings-websocket.html
 ---
 
-The Ditto Protocol message can be sent *as is* as [WebSocket](https://tools.ietf.org/html/rfc6455) message.
+[Ditto Protocol](protocol-overview.html) messages can be sent *as is* as [WebSocket](https://tools.ietf.org/html/rfc6455) message.
 The Ditto Protocol JSON must be sent as `UTF-8` encoded String payload.
 
 

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

@@ -9,7 +9,7 @@ HTML5 <a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossar
 to get notified when the state of **Digital Twins** change.
 
 This is the second mechanism of Ditto in order to get [change notifications](basic-changenotifications.html).
-The benefit of this mechanism in contrary to the [WebSocket](protocol-bindings-websocket.html) channel is that it is
+The benefit of this mechanism in contrary to the [WebSocket](httpapi-protocol-bindings-websocket.html) channel is that it is
 even easier to open a SSE connection from the client than a WebSocket and that in Ditto's interpretation of SSEs the
 events sent back from the backend have the same JSON structure as the HTTP API on which they are invoked. 
 

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

@@ -6,22 +6,26 @@ permalink: protocol-bindings.html
 ---
 
 A protocol binding defines how the Ditto protocol messages are transported using a specific network protocol e.g.
-“Ditto Protocol over WebSocket”.
+"Ditto Protocol over WebSocket".
 The binding defines a set of rules how Ditto protocol messages are mapped to network protocol messages and back.
 
 Currently the following protocol bindings are supported:
 
-
-* [WebSocket Binding](protocol-bindings-websocket.html)
-* [AMQP 1.0 Binding](protocol-bindings-amqp10.html)
+* [WebSocket](httpapi-protocol-bindings-websocket.html)
+* [AMQP 1.0](connectivity-protocol-bindings-amqp10.html)
+* [AMQP 0.9.1](connectivity-protocol-bindings-amqp091.html)
 
 
 ## Content Type
 
-Whenever sending messages towards Ditto, the following content type has to be specified in a protocol-specific way.
+When sending messages towards Ditto, the following content type has to be specified in a protocol-specific way given that
+the messages are already in [Ditto Protocol](protocol-overview.html) format.
 
 All [change notifications](basic-changenotifications.html) emitted by Ditto will also contain the `content-type`:
 
 ```
 application/vnd.eclipse.ditto+json
 ```
+
+For messages which are not yet in that format, the [payload mapping](connectivity-mapping.html) of Ditto's 
+[connectivity](connectivity-overview.html) may be used to bring the messages in that format.

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

@@ -135,7 +135,7 @@ bindings. We will use the WebSocket binding for now. With it, it is amazingly ea
 receive Messages sent *to* or *from* Things. You only need to fulfill these *three* simple requirements:
 
 1. Having an open connection to the Ditto WebSocket
-2. Having sent the [WebSocket binding specific message](protocol-bindings-websocket.html#request-events) 
+2. Having sent the [WebSocket binding specific message](httpapi-protocol-bindings-websocket.html#request-events) 
 `START-SEND-MESSAGES` to the WebSocket to be able to retrieve Messages
 3. You are allowed ([authorized](basic-auth.html)) to receive Messages 
 

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

@@ -14,7 +14,7 @@ In order to comply with the Ditto Protocol, a Protocol message must consist of
 ## Ditto Protocol
 
 The communication protocol envelope is implicitly defined by the underlying messaging system 
-(e.g. [WebSocket](protocol-bindings-websocket.html)) used to transport/serialize the messages over the wire.
+(e.g. [WebSocket](httpapi-protocol-bindings-websocket.html)) used to transport/serialize the messages over the wire.
 Please refer to the respective [communication protocol binding](protocol-bindings.html) for information how to encode
 the data in a protocol specific way.
 

documentation/src/main/resources/pages/ditto/release_notes_010M3.md

@@ -21,7 +21,7 @@ A new service "ditto-amqp-bridge" was added in order to be able establish a conn
 endpoints like for example [Eclipse Hono](https://eclipse.org/hono/).
 
 That way messages in [Ditto Protocol](protocol-overview.html) coming from Eclipse Hono can be processed. 
-For more details, please have a look at the [AMQP 1.0 binding](protocol-bindings-amqp10.html) and the 
+For more details, please have a look at the [AMQP 1.0 binding](connectivity-protocol-bindings-amqp10.html) and the 
 [AMQP-Bridge architecture](architecture-services-connectivity.html).
 
 ### [DevOps commands HTTP endpoint](https://github.com/eclipse/ditto/pull/55)