diff --git a/doc/mix.exs b/doc/mix.exs index f94278b92..231224a8b 100644 --- a/doc/mix.exs +++ b/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", diff --git a/doc/pages/api/001-intro_api.md b/doc/pages/api/001-intro_api.md index 7cd0e6487..b6223d8f1 100644 --- a/doc/pages/api/001-intro_api.md +++ b/doc/pages/api/001-intro_api.md @@ -1,7 +1,18 @@ # Introduction +## REST API + Join Puppy Lion and have some fun with Astarte! -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:///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) diff --git a/doc/pages/architecture/030-interface.md b/doc/pages/architecture/030-interface.md index 57374e638..103a774e4 100644 --- a/doc/pages/architecture/030-interface.md +++ b/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 diff --git a/doc/pages/architecture/040-interface_schema.md b/doc/pages/architecture/040-interface_schema.md index d6dd9a53c..cdb191a16 100644 --- a/doc/pages/architecture/040-interface_schema.md +++ b/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 diff --git a/doc/pages/user/001-intro_user.md b/doc/pages/user/001-intro_user.md index 65cef155e..fe84d8c57 100644 --- a/doc/pages/user/001-intro_user.md +++ b/doc/pages/user/001-intro_user.md @@ -2,8 +2,6 @@ Join Puppy Lion and have some fun with Astarte! -**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. diff --git a/doc/pages/user/052-using_channels.md b/doc/pages/user/052-using_channels.md index 136652565..c159b8a62 100644 --- a/doc/pages/user/052-using_channels.md +++ b/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:///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