Docs

.github/workflows/run-tests.yml

@@ -33,8 +33,8 @@ jobs:
   run-tests:
     strategy:
       matrix:
-        os: ["ubuntu-20.04", "ubuntu-22.04"]
-        python: ["3.8", "3.9", "3.10"]
+        os: [ubuntu-22.04]
+        python: ['3.10', '3.11']
 
     runs-on: ${{ matrix.os }}
 

README.md

@@ -4,12 +4,23 @@ and utility pages for administration and certificate management.
 This library cannot be installed as a VOLTTRON agent is.
 Rather, it must be installed as a python package.
 
+![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)
+![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)
 [![Run Pytests](https://github.com/eclipse-volttron/volttron-lib-web/actions/workflows/run-tests.yml/badge.svg)](https://github.com/eclipse-volttron/volttron-lib-web/actions/workflows/run-tests.yml)
 [![pypi version](https://img.shields.io/pypi/v/volttron-lib-web.svg)](https://pypi.org/project/volttron-lib-web/)
 
-## Requirements
-* python >=3.8
+# Requires
+
+* python >= 3.10
 * volttron >= 10.0
+* jinja2-cli >= 0.7.0
+* passlib >= 1.7.4
+* PyJWT == 1.7.1
+* treelib >= 1.6.1
+* werkzeug >= 2.1.2
+* ws4py = >= 0.5.1
+* requests >= 2.28.1
+* argon2-cffi >= 21.3.0
 
 ## Installation
 This library can be installed using pip:
@@ -66,7 +77,7 @@ configuration shown above). This will create a file called web-users.json in the
 
 Additionally, the web service provides a RESTful API which can be used by other applications. Full documentation for
 the API is available on 
-[Readthedocs](https://volttron.readthedocs.io/en/main/platform-features/web-api/introduction.html).
+[Readthedocs](https://volttron.readthedocs.io/en/modular/external-docs/volttron-lib-web/docs/source/index.html).
 
 Note that it is necessary for most API endpoints to have previously created a username and password for authentication
 by visiting the /admin page or by manually copying or creating a web-users.json file. Authentication can then be

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/authentication-endpoints.rst

@@ -0,0 +1,113 @@
+.. _Authentication-Endpoints:
+
+========================
+Authentication EndPoints
+========================
+
+The VOLTTRON Web API requires the use of bearer tokens to access resources.  These tokens
+are JSON Web Tokens (JWT) and are provided by the two ``/authenticate`` endpoints (``POST``
+and ``PUT``).  Two classes of token are provided to the user:
+
+- Refresh Tokens:
+    Refresh tokens are long-lived, and used can be used to obtain a new short-lived access
+    token. Refresh tokens are obtained by providing a valid username and password to the
+    ``POST /authenticate`` endpoint. The refresh token SHOULD be kept secure on the
+    client side, and SHOULD NOT be provided to API call other than to
+    ``PUT /authenticate``.
+
+- Access Tokens:
+    An access token are short-lived tokens required to obtain resources or services provided
+    by other API endpoints. The access token is obtained using the ``PUT /authenticate``
+    endpoint. For convenience, an inital access token is provided by the
+    ``POST /authenticate`` endpoint as well, but as use the ``POST`` method requires
+    sending credentials to the server, this should only be used on the first call, with
+    ``PUT`` being used thereafter to obtain new access tokens until the refresh token has
+    also expired.
+
+.. note:: Authentication begins by obtaining a JWT bearer refresh token from the
+    ``POST /authenticate`` endpoint. An initial access token is provided by this endpoint
+    as well. Subsequent access tokens are then obtained by providing the refresh token to the
+    ``PUT /authenticate`` endpoint without resending of credentials.
+
+----------------------------------------------------------------------------
+
+POST /authenticate
+==================
+
+Provide authentication credentials to receive refresh token.
+
+The user provides a username and password in the request body. If authentication succeeds,
+the endpoint will returna a JWT bearer refresh token with user’s claims. An initial access
+token is also returned. The refresh token can then be provided to ``PUT /authenticate``
+to obtain new short-lived access tokens, as needed, without sending the username and
+password again until the refresh token expires.
+
+Request:
+--------
+- Content Type: ``application/json``
+- Body:
+
+  .. code-block:: JSON
+
+        {
+            "username": "<username>",
+            "password": "<password>"
+        }
+
+Response:
+---------
+
+* **With valid username and password:** ``200 OK``
+    - Content Type: ``application/json``
+    - Body:
+
+      .. code-block:: JSON
+
+            {
+                "refresh_token": "<jwt_refresh_token>",
+                "access_token": "<jwt_access_token>"
+            }
+
+* **With invalid username and password:** ``401 Unauthorized``
+
+--------------
+
+PUT /authenticate
+=================
+
+Renew access token.
+
+The user provides a valid refresh token (provided by ``POST /authenticate``) in the
+Authorization header to obtain a fresh access token. A current access token MAY also
+be provided, as needed, in the request body to keep open any existing subscriptions.
+All subsequent requests to any endpoint should include the new token, and the old
+access token should be discarded.
+
+Request:
+--------
+
+- Content Type: ``application/json``
+- Authorization: ``BEARER <jwt_refresh_token>``
+- Body (optional):
+
+  .. code-block:: JSON
+
+        {
+          "current_access_token": "<jwt_access_token>"
+        }
+
+Response:
+---------
+
+* **With valid refresh token:** ``200 OK``
+    - Content Type: ``application/json``
+    - Body:
+
+      .. code-block:: JSON
+
+            {
+                "access_token": "<new_jwt_access_token>"
+            }
+
+* **With invalid or mismatched username, password, or token:**
+   ``401 Unauthorized``

docs/source/conf.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*- {{{
+# ===----------------------------------------------------------------------===
+#
+#                 Installable Component of Eclipse VOLTTRON
+#
+# ===----------------------------------------------------------------------===
+#
+# Copyright 2022 Battelle Memorial Institute
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy
+# of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# ===----------------------------------------------------------------------===
+# }}}
+
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'VOLTTRON Web Service'
+copyright = '2022, Pacific Northwest National Lab'
+author = 'Pacific Northwest National Lab'
+
+release = '0.2'
+version = '0.2.0-rc'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+# epub_show_urls = 'footnote'

docs/source/index.rst

@@ -0,0 +1,142 @@
+.. _Web-API:
+
+======================================
+RESTful Web Interface
+======================================
+
+The VOLTTRON User Interface API (VUI) is provided by the VOLTTRON Web Service, and is
+intended to provide capabilities for building fully featured frontend applications.
+The VUI is a RESTful HTTP API for communicating with components of the VOLTTRON system.
+
+Installation
+------------
+The VUI is a built-in part of the VOLTTRON Web Service. To enable to VOLTTRON Web Service,
+install the volttron-lib-web library:
+
+.. code-block:: bash
+
+    pip install volttron-lib-web
+
+Once the library is installed, VOLTTRON will not be able to start until the web service is configured.
+Configurations for services, including this, reside in a service_config.yml file in the VOLTTRON_HOME directory
+(by default ~/.volttron/service_config.yml). If this file does not already exist, create it.
+To configure the web service, include the following:
+
+.. code-block:: yaml
+
+    volttron.services.web:
+      enabled: true
+      kwargs:
+        bind_web_address: http://192.168.0.101:8080
+        web_secret_key: some_string # If not using SSL.
+        web_ssl_cert: /path/to/certificate # Path to the SSL certificate to be used by the web service.
+        web_ssl_key: /path/to/key # Path to the SSL secret key file used by web service.
+
+The value of the ``bound_web_address`` key represents address to which the platform web service listens
+for HTTP(s) requests. Typical addresses would be ``https://<hostname_or_ip>:8443`` or
+``http://<hostname_or_ip>:8080``, and will most often be the IP address of the host on which the web service
+is installed. Setting the bind_web_address to 0.0.0.0 will bind to all interfaces on the machine. 127.0.0.1 or
+localhost can be used if it is not desired for the web services to be reachable by other hosts.
+
+.. Note::
+
+    If a hostname is used, it must be resolvable for the service to work as expected.
+
+The port number (after the colon) can be any port which is not bound to another service on the host mahcine.
+80 or 8080 are common ports when not using SSL. 443 and 8443 are common ports to use when using SSL.
+
+HTTPS is strongly recommended. If using SSL, both web_ssl_certificate and web_ssl_key are required
+and web_secret_key should not be included. If SSL is not desired, provide a web_secret_key instead and remove the
+lines for the web_ssl_cert and web_ssl_key. Any string can be used for the web_secret_key.
+
+Additionally, in order to use many of the API endpoints, an instance name must be set in the VOLTTRON platform
+configuration file in VOLTTRON_HOME (by default ~/.volttron/config).  If this file does not already exist, create it.
+Ensure that it contains at least the following (where "my_instance_name" will be the name of this platform):
+
+.. code-block:: ini
+
+    [volttron]
+    instance-name=my_instance_name
+
+
+Finally, a user must be configured in the ``$VOLTTRON_HOME/web-users.json`` file to allow authentication to the API.
+This file can be generated, if it does not exist, by navigating to `bind-web-address`/admin in a web browser and
+creating a user and password:
+
+.. image:: files/create_admin_user.png
+
+.. code-block:: json
+
+    {
+    "my_user":{
+        "hashed_password":"$argon2id$v=19$m=102400,t=2,p=8$tbb2PgdA6B3jnPOeUwrB+A$yGA2xYOXld+COq4opWbs3Q",
+        "groups":["admin", "vui"]
+        }
+    }
+
+Users with the "vui" claim in `groups` will now be able to use the API by sending requests
+to endpoints with paths on `bind-web-address` beginning with `/vui`. For example, where `bind-web-address` has been
+set to ``https://localhost:8443`` the following HTTP request (with a proper
+:ref:`HTTP Authorization Header <Authentication-Endpoints>`) may be used to retrieve the root endpoint of the API:
+
+::
+
+    GET https://localhost:8443/vui/
+
+Access to the API may be disabled by removing "vui" from the list of groups in ``$VOLTTRON_HOME/web-users.json`` for any user which should not have access
+to the API.
+
+Path Structure
+---------------
+
+
+Paths to endpoints consist of alternating constant and variable segments, and are designed
+to be readable and discoverable:
+
+.. image:: files/path_structure.png
+
+Get requests to non-leaf nodes typically return a `route-options` JSON object which gives additional possible paths
+within the API. For instance, a GET request send to the path `/vui` will return:
+
+.. code-block:: json
+
+    {
+    "route_options": {
+        "platforms": "/vui/platforms"
+        }
+    }
+
+Available Endpoints
+-------------------
+
+
+Endpoints which are currently provided by the API are described in detail in the
+following sections:
+
+- :ref:`Authentication <Authentication-Endpoints>`: Endpoints for authenticating to the the API.
+- :ref:`Platforms <Platforms-Endpoints>`: Endpoints for working with a particular platform.
+    - :ref:`Agents <Platforms-Agents-Endpoints>`: Endpoints for working with agents on the platform.
+        - :ref:`Configs <Platforms-Agents-Configs-Endpoints>`: Endpoints for managing the configuration store for agents
+          on the platform.
+        - :ref:`Enabled <Platforms-Agents-Enabled-Endpoints>`: Endpoints for enabling, disabling, and setting the
+          start priority of agents on the platform.
+        - :ref:`RPC <Platforms-Agents-Rpc-Endpoints>`: Endpoints allowing, discovery, inspection, and calling of
+          remote procedure calls to agents running on the platform.
+        - :ref:`Running <Platforms-Agents-Running-Endpoints>`: Endpoints for starting and stopping agents on the
+          platform.
+        - :ref:`Status <Platforms-Agents-Status-Endpoints>`: Endpoints for determining status information for agents
+          running on the platform.
+        - :ref:`Tag <Platforms-Agents-Tag-Endpoints>`: Endpoints for getting, setting, and deleting the tag of agents.
+    - :ref:`Devices <Platforms-Devices-Endpoints>`: Endpoints for getting, setting, and resetting devices on the
+      platform.
+    - :ref:`Historians <Platforms-Historians-Endpoints>`: Endpoints for querying data from historians on the platform.
+    - :ref:`Pubsub <Platforms-Pubsub-Endpoints>`: Endpoints for subscribing and publishing to the message bus on the
+      platform.
+    - :ref:`Status <Platforms-Status-Endpoints>`: Endpoints for determining and clearing the status of all agents on
+      the platform.
+
+ .. toctree::
+    :hidden:
+
+    Authentication <authentication-endpoints>
+    Platforms <platform-endpoints>