Merge pull request #989 from matt-mazzucato/fwport-1.1-into-1.2

Forward-port from release-1.1

doc/mix.exs

@@ -41,7 +41,7 @@ defmodule Doc.MixProject do
         "User Guide": ~r"/user/",
         "Administrator Guide": ~r"/administrator/",
         Tutorials: ~r"/tutorials/",
-        "REST API Reference": ~r"/api/"
+        "API Reference": ~r"/api/"
       ],
       groups_for_modules: [
         "App Engine": ~r"Astarte.AppEngine",

doc/pages/api/001-intro_api.md

@@ -1,7 +1,18 @@
 # Introduction
 
+## REST API
+
 <img align="right" src="assets/mascot_developer.svg" style="border:20px solid transparent" alt="Join Puppy Lion and have some fun with Astarte!" width="40%" />
 
-Astarte's APIs are documented through [Swagger](https://swagger.io/). Your Astarte installation probably already has Swagger UI support, which serves as the reference for your installed APIs.
+Astarte's APIs are documented through [Swagger](https://swagger.io/). Your Astarte installation
+probably already has Swagger UI support, which serves as the reference for your installed APIs.
 
 To browse API documentation online, [follow this link](api/index.html).
+
+## WebSocket Astarte Channels
+
+The AppEngine API for Astarte Channels is located at the URL:
+`ws://<astarte-base-url>/appengine/v1/socket/websocket`.
+
+To learn how to use the Channels API, you can read the documentation at:
+[Using Astarte Channels (WebSockets)](user/052-using_channels.md)

doc/pages/architecture/030-interface.md

@@ -225,9 +225,9 @@ of a valid aggregated interface mapping:
 Additional limitations (which stem from the MQTT protocol specification) can be outlined. When using
 parametric endpoints, the actual values used in place of parameter placeholders must fulfill the
 following requirements:
-* endpoint parameters must be UTF-8 encoded strings;
-* endpoint parameters must not contain the following characters: `+` and `#`. In particular, those
-  characters are treated as wildcards for MQTT topics and therefore must be avoided;
+* endpoint parameters must be non-empty UTF-8 encoded strings;
+* endpoint parameters must not contain the following characters: `+` and `#`. Those characters are
+  treated as wildcards for MQTT topics and therefore must be avoided;
 * endpoint parameters must not contain the `/` character.
 
 ## Aggregation

doc/pages/architecture/040-interface_schema.md

@@ -154,7 +154,8 @@ Additional properties are allowed.
 The template of the path. This is a UNIX-like path (e.g. /my/path) and can be parametrized.
 Parameters are in the %{name} form, and can be used to create interfaces which represent
 dictionaries of mappings. When the interface aggregation is object, an object is composed by all the
-mappings for one specific parameter combination.
+mappings for one specific parameter combination. Refer to the mapping section of the
+[interface](030-interface.html) page for further details on allowed parameter substitution values.
 
 * **Type**: `string`
 * **Required**: Yes

doc/pages/user/001-intro_user.md

@@ -2,8 +2,6 @@
 
 <img align="right" src="assets/mascot_developer.svg" style="border:20px solid transparent" alt="Join Puppy Lion and have some fun with Astarte!" width="40%" />
 
-**This documentation page describes a development version, for production systems please use the [stable version](https://docs.astarte-platform.org/latest) instead.**
-
 Astarte is an Open Source IoT platform focused on Data management. It takes care of everything from collecting data from devices to delivering data to end-user applications. To achieve such a thing, it uses a mixture of mechanisms and paradigm to store organized data, perform live queries.
 
 This guide focuses on daily operations for Astarte users and integrators. It goes through fundamental operations such as setting up triggers, querying APIs, integrating 3rd party applications and more.

doc/pages/user/052-using_channels.md

@@ -6,6 +6,9 @@ provide such a thing over [WebSockets](https://en.wikipedia.org/wiki/WebSocket)
 WebSockets can be used natively from a Web Browser and follow the same authentication pattern as a
 standard HTTP call.
 
+The AppEngine API for Astarte Channels is located at the URL:
+`ws://<astarte-base-url>/appengine/v1/socket/websocket`.
+
 Astarte Channels define a semantic on top of Phoenix Channels which allows read-only monitoring of
 `device` Interfaces. Authentication and Authorization over Channels happens in the very same way as
 `AppEngine`, and the `a_ch` claim in the token is respected when joining rooms and installing