diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 0309202..cde37bb 100644 --- a/.github/workflows/run-tests.yml +++ b/.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 }} diff --git a/README.md b/README.md index 7f76804..c2ed06f 100644 --- a/README.md +++ b/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: @@ -55,7 +66,7 @@ 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. -Full VOLTTRON documentation is available at [VOLTTRON Readthedocs](https://volttron.readthedocs.io) +Full VOLTTRON documentation is available at [VOLTTRON Readthedocs](https://eclipse-volttron.readthedocs.io/) ## Use @@ -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://eclipse-volttron.readthedocs.io/en/latest/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 @@ -92,7 +103,7 @@ print(platforms.json()) Please see the following for contributing guidelines [contributing](https://github.com/eclipse-volttron/volttron-core/blob/develop/CONTRIBUTING.md). -Please see the following helpful guide about [developing modular VOLTTRON agents](https://github.com/eclipse-volttron/volttron-core/blob/develop/DEVELOPING_ON_MODULAR.md) +Please see the following helpful guide about [developing modular VOLTTRON agents](https://eclipse-volttron.readthedocs.io/en/latest/developing-volttron/developing-agents/agent-development.html) # Disclaimer Notice diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/docs/source/authentication-endpoints.rst b/docs/source/authentication-endpoints.rst new file mode 100644 index 0000000..6abb31f --- /dev/null +++ b/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:: javascript + + { + "username": "", + "password": "" + } + +Response: +--------- + +* **With valid username and password:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "refresh_token": "", + "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 `` +- Body (optional): + + .. code-block:: javascript + + { + "current_access_token": "" + } + +Response: +--------- + +* **With valid refresh token:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "access_token": "" + } + +* **With invalid or mismatched username, password, or token:** + ``401 Unauthorized`` diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..034dcef --- /dev/null +++ b/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' diff --git a/docs/source/files/create_admin_user.png b/docs/source/files/create_admin_user.png new file mode 100644 index 0000000..1e2fe94 Binary files /dev/null and b/docs/source/files/create_admin_user.png differ diff --git a/docs/source/files/path_structure.png b/docs/source/files/path_structure.png new file mode 100644 index 0000000..6f1ead8 Binary files /dev/null and b/docs/source/files/path_structure.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..f530249 --- /dev/null +++ b/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://:8443`` or +``http://: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:: javascript + + { + "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 `) 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:: javascript + + { + "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 `: Endpoints for authenticating to the the API. +- :ref:`Platforms `: Endpoints for working with a particular platform. + - :ref:`Agents `: Endpoints for working with agents on the platform. + - :ref:`Configs `: Endpoints for managing the configuration store for agents + on the platform. + - :ref:`Enabled `: Endpoints for enabling, disabling, and setting the + start priority of agents on the platform. + - :ref:`RPC `: Endpoints allowing, discovery, inspection, and calling of + remote procedure calls to agents running on the platform. + - :ref:`Running `: Endpoints for starting and stopping agents on the + platform. + - :ref:`Status `: Endpoints for determining status information for agents + running on the platform. + - :ref:`Tag `: Endpoints for getting, setting, and deleting the tag of agents. + - :ref:`Devices `: Endpoints for getting, setting, and resetting devices on the + platform. + - :ref:`Historians `: Endpoints for querying data from historians on the platform. + - :ref:`Pubsub `: Endpoints for subscribing and publishing to the message bus on the + platform. + - :ref:`Status `: Endpoints for determining and clearing the status of all agents on + the platform. + + .. toctree:: + :hidden: + + Authentication + Platforms diff --git a/docs/source/platform-endpoints.rst b/docs/source/platform-endpoints.rst new file mode 100644 index 0000000..8514811 --- /dev/null +++ b/docs/source/platform-endpoints.rst @@ -0,0 +1,133 @@ +.. _Platforms-Endpoints: + +=================== +Platforms Endpoints +=================== + + +Platforms endpoints expose functionality associated with specific +VOLTTRON platforms. + +As all functionality of VOLTTRON is the purview of one or another +platform, the /platforms tree forms the core of the VOLTTRON User +Interface API. Other top level partitions of the API consist of +convenience methods which refer to endpoints within /platforms. + +The platforms tree currently provides access to four major categories of endpoint, each of which are described in detail +through the following links: + +* :ref:`Agents `: Endpoints pertaining to a specific agent (e.g. RPC) +* :ref:`Devices `: Endpoints for discovering, getting, and setting data about the current + state of devices on the platform. +* :ref:`Historians `: Endpoints for querying data from historians. +* :ref:`PubSub `: Endpoints for subscription and publication to message bus topics. +* :ref:`Status `: Endpoints for retrieving and clearing status of all agents on the + platform. + +.. attention:: + All endpoints in this tree require authorization using a JWT bearer + token provided by the ``POST /authenticate`` or ``PUT /authenticate`` + endpoints. + +-------------------------------------------------------------------------------- + +GET /platforms +============== + +Obtain routes for connected platforms. + +A ``GET`` request to the ``/platforms`` endpoint will return a JSON object containing routes to available platforms. +Available routes are included in a "route_options" object. The keys of the "route_options" object are the name of each +platform which is currently reachable through the API, and the values contain a route to an endpoint for the platform. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/", + "": "/platforms/" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +--------------------------------------------------------------------------------------------------------------------- + +GET /platforms/:platform +======================== + +Obtain routes available for a specific platform. + +A ``GET`` request to the ``/platforms/:platform`` endpoint (where ``:platform`` is the instance name of a specific +platform) will return a JSON object containing routes to endpoints which are available for the requested platform. +Available routes are included in a "route_options" object. The keys of the "route_options" object are the name of each +endpoint which the platform supports, and the values contain a route to that endpoint for this platform. The currently +implemented possibilities include: :ref:`agents `, +:ref:`devices `, :ref:`historians `, +:ref:`pubsub ` and :ref:`status `. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/", + "": "/platforms/:platform/" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + Agents + Configs + Devices + Health + Historians + Pubsub + Status diff --git a/docs/source/platforms/agent-endpoints.rst b/docs/source/platforms/agent-endpoints.rst new file mode 100644 index 0000000..96ddf56 --- /dev/null +++ b/docs/source/platforms/agent-endpoints.rst @@ -0,0 +1,124 @@ +.. _Platforms-Agents-Endpoints: + +========================== +Platforms Agents Endpoints +========================== + +Platforms Agents endpoints expose functionality associated with applications +running on a VOLTTRON platform. + +Platforms Agents endpoints currently include: + * :ref:`Configs `: Endpoints for managing the configuration store for agents + on the platform. + * :ref:`Enabled `: Endpoints for enabling, disabling, and setting the start + priority of agents on the platform. + * :ref:`Running `: Endpoints for starting and stopping agents on the platform. + * :ref:`RPC `: Endpoints allowing, discovery, inspection, and calling of remote + procedure calls to agents running on the platform. + * :ref:`Status `: Endpoints for determining the status information for an agent + running on the platform. + * :ref:`Tag `: Endpoints for getting, setting, and deleting the tag of agents. + +.. attention:: + All Platforms Agents endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents +=============================== + +Return routes for the agents installed on the platform. + +Accepts a two query parameters: + +* ``agent-state`` accepts one of three string values: + - *"running"* (default): Returns only those agents which are currently running. + - *"installed"*: Returns all installed agents. + - *"packaged"*: Returns filenames of packaged agents on the platform which can be installed. +* ``include-hidden`` (default=False): When True, includes system agents which would not normally be displayed by vctl status. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/agents/:vip_identity", + "": "/platforms/:platform/agents/:vip_identity" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +------------------------------------------------------------------------------------------ + +GET /platforms/:platform/agents/:vip-identity +============================================= + +Return routes for the supported endpoints for an agent installed on the platform. +Currently implemented endpoints include :ref:`RPC `. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/agents/:vip_identity/", + "": "/platforms/:platform/agents/:vip_identity/" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + ConfigStore + Enabled + Health + RPC + Running + Status + Tag diff --git a/docs/source/platforms/agents/config-endpoints.rst b/docs/source/platforms/agents/config-endpoints.rst new file mode 100644 index 0000000..ded16a8 --- /dev/null +++ b/docs/source/platforms/agents/config-endpoints.rst @@ -0,0 +1,233 @@ +.. _Platforms-Agents-Configs-Endpoints: + +================================== +Platforms Agents Configs Endpoints +================================== + +Platforms Agents Configs endpoints expose functionality associated with agent configurations stored in the +VOLTTRON Configuration Store. + +.. attention:: + All Platforms Configs endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:vip_identity/configs +===================================================== + +Get routes to available configuration files for the specified agent. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response +-------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + ":config_file_name": "/platforms/:platform/agents/:vip_identity/configs/:config_file_name", + "": "/platforms/:platform/agents/:vip_identity/configs/:config_file_name", + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +-------------------------------------------------------------------------------------------------- + +POST /platforms/:platform/agents/:vip_identity/configs/ +======================================================== + +Save a new configuration file to the config store. + +The file name should be passed in the query parameter file-name. + +The file should match the content type and contents which the VOLTTRON configuration store expects. +The configuration store currently accepts only JSON, CSV, or RAW files. The content type header should match the type +of file being sent (``application/json``, ``text/csv``, or ``text/plain`` respectively). This endpoint +will return 409 Conflict if the configuration file already exists. In this case, the user should use +``PUT /platforms/:platform/agents/:vip_identity/configs/:file_name`` if modification of the existing file is truly +intended. + +Request: +-------- + +* Authorization: ``BEARER `` +* Content Type: ``application/json``, ``text/csv``, or ``text/plain`` +* Body: Contents of configuration file. + +Response +-------- + +* **With valid BEARER token on success:** ``201 Created`` + - Location: /platforms/:platform/agents/:vip_identity/configs/:file_name + - Content Type: ``application/json``, ``text/csv``, or ``text/plain`` + - Body: Contents of the configuration file. + +* **With valid BEARER token on failure:** ``400 Bad Request`` or ``409 Conflict`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +----------------------------------------------------------------------------------------- + +DELETE /platforms/:platform/agents/:vip_identity/configs/ +========================================================== + +Remove the configuration store for an agent. This endpoint will return ``409 Conflict`` if +the store for this agent is not empty. To remove all existing configurations for an agent from the config store +and delete the store, ``true`` must be passed to the ``all`` query parameter. + +Request: +-------- + +* Authorization: ``BEARER `` +* Query Parameters: + * ``all``: Boolean (default ``false``) + +Response +-------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` or ``409 Conflict`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +------------------------------------------------------------------------------------------------ + +GET /platforms/:platform/agents/:vip_identity/configs/:config_name +================================================================== + +Get a configuration file for the agent from the config store. + +The configuration store can currently return JSON, CSV, or RAW files. If the Accept header is not set, +the configuration store will return JSON by default. If the client wishes to restrict the type of file received, +it should set the Accept header to the correct MIME type(s) (``application/json``, ``text/csv``, or ``text/plain`` +respectively). + +Request: +-------- + +* Authorization: ``BEARER `` + +Response +-------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json``, ``text/csv``, or ``text/plain`` + - Body: Contents of the configuration file. + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +----------------------------------------------------------------------------------------- + +PUT /platforms/:platform/agents/:vip_identity/configs/:config_name +================================================================== + +Overwrite a configuration file already in the config store. + +The file should match the content type and contents which the VOLTTRON configuration store expects. +The configuration store currently accepts only JSON, CSV, or RAW files. The content type header should match the type +of file being sent (``application/json``, ``text/csv``, or ``text/plain`` respectively). + +Request: +-------- + +* Authorization: ``BEARER `` +* Content Type: ``application/json``, ``text/csv``, or ``text/plain`` +* Body: Contents of configuration file. + +Response +-------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +----------------------------------------------------------------------------------------- + +DELETE /platforms/:platform/agents/:vip_identity/configs/:config_name +===================================================================== + +Remove an existing configuration file for the agent from the config store. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response +-------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/enabled-endpoints.rst b/docs/source/platforms/agents/enabled-endpoints.rst new file mode 100644 index 0000000..5f94d03 --- /dev/null +++ b/docs/source/platforms/agents/enabled-endpoints.rst @@ -0,0 +1,119 @@ +.. _Platforms-Agents-Enabled-Endpoints: + +================================== +Platforms Agents Enabled Endpoints +================================== + +Platforms Agents Enabled endpoints expose functionality associated with the enabled status of agents on the platform. +This includes determining whether an agent is enabled (and with what start priority), as well as enabling and disabling +the agent. + +.. attention:: + All Platforms Agents Enabled endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:agent/enabled +============================================== + +Retrieve the enabled status and priority of the specified agent. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: application/json + - Body: + + .. code-block:: javascript + + { + "status": true|false, + "priority": int + } +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + + +-------------- + +PUT /platforms/:platform/agents/:agent/enabled +============================================== + +Enable the specified agent. + +Accepts the ``priority`` query parameter to set the start priority of the agent. Allowable prioirties range from 0 to +99. If the priority is not given, the agent will be enabled with a priority of 50. + +Request: +-------- + +* Authorization: ``BEARER `` + + +Response: +--------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +DELETE /platforms/:platform/agents/:agent/enabled +================================================= + +Disable the specified agent. + +Request: +-------- + +* Authorization: ``BEARER `` + + +Response: +--------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/health-endpoints.rst b/docs/source/platforms/agents/health-endpoints.rst new file mode 100644 index 0000000..e923202 --- /dev/null +++ b/docs/source/platforms/agents/health-endpoints.rst @@ -0,0 +1,55 @@ +.. _Platforms-Agents-Health-Endpoints: + +================================== +Platforms Agents Health Endpoints +================================== + +Platforms Agents Health endpoints expose functionality associated with getting health information for +a single agent running on a VOLTTRON platform. + +.. attention:: + All Platforms Agents Health endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:agent/health +============================================== + +Retrieve health information for the specified agent. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: application/json + - Body: + + .. code-block:: javascript + + { + "status": "", + "context": {"": "agent_specific_values>"}, + "last_updated": "" + } +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/rpc-endpoints.rst b/docs/source/platforms/agents/rpc-endpoints.rst new file mode 100644 index 0000000..d04772c --- /dev/null +++ b/docs/source/platforms/agents/rpc-endpoints.rst @@ -0,0 +1,164 @@ +.. _Platforms-Agents-Rpc-Endpoints: + +============================== +Platforms Agents RPC Endpoints +============================== + + +RPC endpoints expose functionality associated with remote procedure calls to agents running on a VOLTTRON platform. + + +.. attention:: + All RPC endpoints require a JWT bearer token obtained through the ``POST /authenticate`` + or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:vip_identity/rpc +================================================= + +Get available remote procedure call endpoints for the specified agent. + +Success will yield a JSON object with available RPC methods as keys and routes for these as values. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/agents/:vip_identity/rpc/:function_name", + "": "/platforms/:platform/agents/:vip_identity/rpc/:function_name" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +GET /platforms/:platform/agents/:vip_identity/rpc/:function_name +================================================================ + +Inspect a remote procedure call method. + +.. note:: + + The information for this endpoint is provided by the `inspect` module. Not all information is available for all + RPC methods. If the data is not available, the key will be absent from the response. + + ``kind`` is an enumeration where the values may be `POSITIONAL_OR_KEYWORD`, `POSITIONAL_ONLY`, or + `KEYWORD_ONLY`. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "params": { + "param_name_1": { + "kind": "POSITIONAL_OR_KEYWORD", + "default": "" + }, + "param_name_2": { + "kind": "KEYWORD_ONLY", + "default": null + } + }, + "doc": "Docstring from the method, if available.", + "source": { + "file": "", + "line_number": "" + } + "return": "" + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +POST /platforms/:platform/agents/:vip_identity/rpc/:function_name +================================================================= + + +Send an remote procedure call to an agent running on a VOLTTRON platform. + +Parameters provided in the request body are passed as arguments to the RPC method. The return value of an RPC call is +defined by the agent, so this may be a scalar value or another JSON object, for instance a list, dictionary, etc. + +Request: +-------- + +* Content Type: ``application/json`` +* Authorization: ``BEARER `` +* Body: + + .. code-block:: javascript + + { + "": "", + "": "" + } + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: Any, as defined by the RPC method. + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/running-endpoints.rst b/docs/source/platforms/agents/running-endpoints.rst new file mode 100644 index 0000000..97e302a --- /dev/null +++ b/docs/source/platforms/agents/running-endpoints.rst @@ -0,0 +1,118 @@ +.. _Platforms-Agents-Running-Endpoints: + +================================== +Platforms Agents Running Endpoints +================================== + +Platforms Agents Running endpoints expose functionality associated with the running status of agents on the platform. +This includes determining whether an agent is running as well as starting and stopping the agent. + +.. attention:: + All Platforms Agents Running endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:agent/running +============================================== + +Retrieve the running status of the specified agent. + +Request: +-------- + + - Authorization: ``BEARER `` + +Response: +--------- + + * **With valid BEARER token on success:** ``200 OK`` + - Content Type: application/json + - Body: + + .. code-block:: javascript + + { + "status": true|false + } + + * **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + + * **With invalid BEARER token:** ``401 Unauthorized`` + + +-------------- + +PUT /platforms/:platform/agents/:agent/running +============================================== + +Start the specified agent. + +Accepts the ``restart`` query parameter to restart an agent. If the agent is already running, an error will be returned +if the restart parameter is not "true". + +Request: +-------- + + - Authorization: ``BEARER `` + + +Response: +--------- + + * **With valid BEARER token on success:** ``204 No Content`` + + * **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + + * **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +DELETE /platforms/:platform/agents/:agent/running +================================================= + +Stop the specified agent. + +Request: +-------- + + - Authorization: ``BEARER `` + + +Response: +--------- + + * **With valid BEARER token on success:** ``204 No Content`` + + * **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + + * **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/status-endpoints.rst b/docs/source/platforms/agents/status-endpoints.rst new file mode 100644 index 0000000..d7de199 --- /dev/null +++ b/docs/source/platforms/agents/status-endpoints.rst @@ -0,0 +1,61 @@ +.. _Platforms-Agents-Status-Endpoints: + +================================= +Platforms Agents Status Endpoints +================================= + +Platforms Agents Status endpoints expose functionality associated with getting status for +a single agent running on a VOLTTRON platform. Only a GET method is currently implemented. + +.. attention:: + All Platforms Agents Status endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:agent/status +============================================= + +Get status for a specific agent on the platform. + +Request: +-------- + + - Authorization: ``BEARER `` + +Response: +--------- + + * **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "name": "", + "uuid": "", + "tag": "", + "priority": "", + "running": , + "enabled": , + "pid": , + "exit_code": + } + + * **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + + * **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/agents/tag-endpoints.rst b/docs/source/platforms/agents/tag-endpoints.rst new file mode 100644 index 0000000..010a5a5 --- /dev/null +++ b/docs/source/platforms/agents/tag-endpoints.rst @@ -0,0 +1,121 @@ +.. _Platforms-Agents-Tag-Endpoints: + +============================== +Platforms Agents Tag Endpoints +============================== + +Platforms Agents Tag endpoints expose functionality associated with tags given to agents on the platform. +Agent tags provide a short name which can be used to identify an agent. + +.. attention:: + All Platforms Agents Tag endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/agents/:agent/tag +========================================== + +Retrieve the tag of the specified agent. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: application/json + - Body: + + .. code-block:: javascript + + { + "tag": "" + } +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + + +-------------- + +PUT /platforms/:platform/agents/:agent/tag +========================================== + +Set the tag to an agent installed on the platform. + +Request: +-------- + +* Authorization: ``BEARER `` +* Content Type: ``application/json`` +* Body: + + .. code-block:: javascript + + { + "tag": "" + } + + +Response: +--------- + +* **With valid BEARER token on success:** ``204 No Content`` +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +DELETE /platforms/:platform/agents/:agent/tag +============================================= + +Remove the tag from an agent installed on a VOLTTRON platform. + +Request: +-------- + +* Authorization: ``BEARER `` + + +Response: +--------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +.. toctree:: + :hidden: + + self diff --git a/docs/source/platforms/config-endpoints.rst b/docs/source/platforms/config-endpoints.rst new file mode 100644 index 0000000..f5a5275 --- /dev/null +++ b/docs/source/platforms/config-endpoints.rst @@ -0,0 +1,249 @@ +.. _Platforms-Configs-Endpoints: + +=========================== +Platforms Configs Endpoints +=========================== + +Platforms Configs endpoints expose functionality associated with platform configuration files. +These endpoints are for platform-level configurations. Agent configurations are managed by +the :ref:`Platforms Agents Configs ` endpoints. + +.. attention:: + All Platforms Configs endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/configs +================================ + +Get routes to available configuration files for the specified platform. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/configs/:config_name", + "": "/platforms/:platform/configs/:config_name" + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +--------------------------------------------------------------- + +POST /platforms/:platform/configs +================================= + +Save a new platform configuration file. + +The file name should be passed in the query parameter file-name. + +The platform configuration files are currently either JSON or INI files. The MIME type of the request will be either +``application/json`` or ``text/plain`` in the case of INI files. This endpoint will return an error if the file already exists. +To update an existing file, use the PUT /platforms/:platform/configs/:file_name endpoint. + +.. warning:: + + Editing platform configuration files can affect the ability of the platform to restart. It is not currently possible + to repair an unstartable platform from the API. Fixing mistakes will require direct access to the device or SSH. + +Request: +-------- + +* Authorization: ``BEARER `` +* Content Type: ``application/json`` or ``text/plain`` +* Query Parameters: + * file-name: The name of the file. If the file will be saved in a subdirectory, ``file-name`` should be a + URL-encoded path to the location of the file relative to the ``VOLTTRON_HOME`` directory. Paths outside of + ``VOLTTRON_HOME`` will be disallowed. +* Body (shown for JSON): + + .. code-block:: + + { + "": , + "": , + } + +Response: +--------- + +* **With valid BEARER token on success:** ``201 Created`` + * Location: ``/platforms/:platform/configs/:file_name`` + * Content Type: ``application/json`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +--------------------------------------------------------------- + +GET /platforms/:platform/configs/:config_name +============================================= + +Get a configuration file for the platform (not for an individual agent). + +The platform configuration files are currently either JSON or INI files. The MIME type of the response will be either +``applciation/json`` or ``text/plain`` in the case of INI files. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - `JSON file:` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "": , + "": , + } + + - `INI file:` + - Content Type: ``text/plain`` + - Body: + + .. code-block:: INI + + [section_name] + key1=value1 + key2=value2 + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +--------------------------------------------------------------- + +PUT /platforms/:platform/configs/:config_name +============================================== + +Replace an existing platform configuration file. + +The platform configuration files are currently either JSON, INI files. The MIME type of the response will be either +``applciation/json`` or ``text/plain`` in the case of INI files. This endpoint will return an error if the file does not +already exist. To create a new file, use the ``POST /platforms/:platform/configs`` endpoint. + +If the file is located in a subdirectory, ``:config_name`` should be a URL-encoded path to the location of the file +relative to the ``VOLTTRON_HOME`` directory. Paths outside of ``VOLTTRON_HOME`` will be disallowed. + +.. warning:: + + Editing platform configuration files can affect the ability of the platform to restart. It is not currently possible + to repair an unstartable platform from the API. Fixing mistakes will require direct access to the device or SSH. + +Request: +-------- + +* Authorization: ``BEARER `` +* Content Type: ``application/json`` or ``text/plain`` +* Body (shown for JSON): + + .. code-block:: + + { + "": , + "": , + } + +Response: +--------- + +* **With valid BEARER token on success:** ``201 Created`` + * Location: ``/platforms/:platform/configs/:file_name`` + * Content Type: ``application/json`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + +--------------------------------------------------------------- + +DELETE /platforms/:platform/configs/:config_name +================================================ + +Delete an existing platform configuration file. + +If the file is located in a subdirectory, ``:config_name`` should be a URL-encoded path to the location of the file +relative to the ``VOLTTRON_HOME`` directory. Paths outside of ``VOLTTRON_HOME`` will be disallowed. + +.. warning:: + + Editing platform configuration files can affect the ability of the platform to restart. It is not currently possible + to repair an unstartable platform from the API. Fixing mistakes will require direct access to the device or SSH. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``204 No Content`` + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` diff --git a/docs/source/platforms/device-endpoints.rst b/docs/source/platforms/device-endpoints.rst new file mode 100644 index 0000000..33eb99d --- /dev/null +++ b/docs/source/platforms/device-endpoints.rst @@ -0,0 +1,314 @@ +.. _Platforms-Devices-Endpoints: + +============================ +Platforms Devices Endpoints +============================ + + +Platform Devices endpoints expose functionality associated with devices managed by a VOLTTRON +platform. An optional topic portion of the route path may be used to select specific devices within +the platform. The selection of devices may then be further refined through the use of query parameters, +as described in *Use of Topics*. + +.. admonition:: Use of Topics + + There is no special meaning to most segments of a topic in the VOLTTRON platform. In the context of + devices, however, the final segment in a full topic denotes a point which can be read or actuated. + Partial topics denote some collection of these point resources. For instance, in the caes of a topic hierarchy + organized as ``:campus/:building/:device/:point``, a topic which is complete up to the ``:device`` level would + yield a single device containing one or more points. A topic complete to the ``:building`` level would include a + set of devices, each containing some set of points. The response to any request containing a full topic will + therefore perform a get or set operation, while a partial topic will typically return a list of routes to + further sub-topics (unless it is explicitly requested that an operation be performed on multiple + points). + + Several methods are available to refine the list of topics: + + Topic Wildcards: + The ``-`` character may be used alone to represent any value for a segment: ``/:campus/-/:device`` + will match all devices with the name :device on the :campus in any building. It is not possible to + use ``-`` as a wildcard within a segment containing other characters: ``/campus/foo-bar/:device`` + will only match a building called “foo-bar”, not one called “foobazbar”. + + Topic-Filtering Query Parameters: + - ``tag`` (default=null): + Filter the result by the provided tag. (This requires that the tagging service be + running and configured.) + - ``regex`` (default=null): + Filter the result by the provided regular expression. The raw regular expression + should follow python re syntax, but must be url-encoded within the query-string. + +.. attention:: + All endpoints in this tree require authorization using a JWT bearer access token provided by the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. +-------------- + +GET /platforms/:platform/devices/:topic +======================================= +Returns a collection of device points and values for a given device topic. + +If no topic, or a parital topic is provided, the output will be a JSON object containing routes to +additional sub-topics matching the provided partial topic. If a full topic is provided, or if the +``read-all`` query parameter is passed, the response will contain data and/or metadata about any +points indicated by the topic. In addition to the ``tag`` and ``regex`` query parameters described +in the *Use of Topics* section above, the following query parameters are accepted: + +* ``read-all`` (default=false): + If true, the response will return entries for every point. These will be a set of JSON objects + with `route`, `writability`, and `value` unless the result is further filtered by the + corresponding query parameters. +* ``routes`` (default=true): + If true, the result will include the route to the points. +* ``writability`` (default=true): + If true, the result will include the writability of the points. +* ``values`` (default=true): + If true, the result will include the value of the points. +* ``config`` (default=false): + If true, the result will include information about the configuration of the point. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: ``application/json`` + - Body: + + + For partial topics, where the ``read-all`` query parameter is false: + This example shows a partial topic, structured as `campus/building/device/point`, + where two segments were provided (the topic provided was `MyCampus/Building1`. + Devices within the building are returned: + + .. code-block:: javascript + + { + "route_options": { + "": "/platforms/:platform/devices/MyCampus/Building1/", + "": "/platforms/:platform/devices/MyCampus/Building1/" + } + } + + + For full topics, or where a partial topic is provided and the ``read-all`` query parameter is true: + This example shows the result of a topic: `MyCampus/Building1/-/Point4`. Note that + the wildcard selects all devices in `Building1` with a point called `Point4`. + ``read-all`` does not need to be ``true`` for this case to get data, as a point segment was provided. + Other query parameters were not provided or were set to their default values. + + .. code-block:: javascript + + { + "MyCampus/Building1/Device1/Point4": { + "route": "/platform/:platform/devices/MyCampus/Building1/Device1/Point4", + "writable": true, + "value": 42 + }, + { + "MyCampus/Building1/Device2/Point4": { + "route": "/platform/:platform/devices/MyCampus/Building1/Device2/Point4", + "writable": false, + "value": 23 + } + } + +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` + + +PUT /platforms/:platform/devices/:topic/ +======================================== + +Sets the value of the specified point and returns its new value and meta-data. In addition to the tag and regex query +parameters described in the Use of Topics section above, the following query parameters are accepted: + +* ``write-all`` (default=false): + If true, the response will write the given value to all points matching the topic. It is *always* necessary to + set write-all=true if more than one point is intended to be written in response to the request. +* ``confirm-values`` (default=false): + If true, the current value of any written points will be read and returned after the write. + +.. warning:: + If an attempt is made to set a point which is not writable, or if multiple points are selected + using a partial topic and/or query parameters and the ``write-all`` query parameter is not set + to ``true``, the response will be ``405 Method Not Allowed``. + +Request: +-------- + +* Authorization: ``BEARER `` + +* Content Type: ``application/json`` + +* Body: + + .. code-block:: javascript + + { + "value": + } + +Response: +--------- + +- **With valid BEARER token on success (confirm-values=false):** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "": { + "route": "/vui/platforms/:platform/devices/:topic", + "set_error": , + "writable": + } + } + +- **With valid BEARER token on success (confirm-values=true):** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "": { + "route": "/vui/platforms/:platform/devices/:topic", + "set_error": , + "writable": , + "value": , + "value_check_error": + } + } + +- **With valid BEARER token if any point is not writable:** + ``405 Method Not Allowed``: + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With valid BEARER token on any other failure:** ``400 Bad Request`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +DELETE /platforms/:platform/devices/:topic/ +=========================================== + +Resets the value of the specified point and returns its new value andmeta-data.In addition to the tag and regex query +parameters described in the Use of Topics section above, the following query parameters are accepted: + + * ``write-all`` (default=false): + If true, the response will write the given value to all points matching the topic. It is *always* necessary to + set write-all=true if more than one point is intended to be written in response to the request. + * ``confirm-values`` (default=false): + If true, the current value of any written points will be read and returned after the write. + +.. warning:: + If an attempt is made to set a point which is not writable, or if multiple points are selected + using a partial topic and/or query parameters and the ``write-all`` query parameter is not set + to ``true``, the response will be ``405 Method Not Allowed``. + +.. warning:: + The request will also fail unless all writes are successful, and any points which would otherwise be set will be + reverted to their previous value. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +- **With valid BEARER token on success (confirm-values=false):** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "": { + "route": "/vui/platforms/:platform/devices/:topic", + "writable": + } + } + +- **With valid BEARER token on success (confirm-values=true):** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "": { + "route": "/vui/platforms/:platform/devices/:topic", + "writable": , + "value": , + "value_check_error": + } + } + +- **With valid BEARER token if any point is not writable:** + ``405 Method Not Allowed``: + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With valid BEARER token on any other failure:** ``400 Bad Request`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With invalid BEARER token:** ``401 Unauthorized`` diff --git a/docs/source/platforms/health-endpoints.rst b/docs/source/platforms/health-endpoints.rst new file mode 100644 index 0000000..74e2cd5 --- /dev/null +++ b/docs/source/platforms/health-endpoints.rst @@ -0,0 +1,55 @@ +.. _Platforms-Health-Endpoints: + +========================== +Platforms Health Endpoints +========================== + +Platforms Health endpoints expose functionality associated with getting health information for +all agents running on a VOLTTRON platform. + +.. attention:: + All Platforms Agents Health endpoints require a JWT bearer token obtained through the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. + +-------------- + +GET /platforms/:platform/health +============================================== + +Retrieve health information for all agents on the platform. + +Request: +-------- + +* Authorization: ``BEARER `` + +Response: +--------- + +* **With valid BEARER token on success:** ``200 OK`` + - Content Type: application/json + - Body: + + .. code-block:: javascript + + { + "": { + "peer": "", + "service_agent": true|false, + "connected": "", + "last_heartbeat": "", + "message": "" + }, + ... + } +* **With valid BEARER token on failure:** ``400 Bad Request`` + - Content Type: ``application/json`` + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +* **With invalid BEARER token:** ``401 Unauthorized`` diff --git a/docs/source/platforms/historian-endpoints.rst b/docs/source/platforms/historian-endpoints.rst new file mode 100644 index 0000000..ef9fd74 --- /dev/null +++ b/docs/source/platforms/historian-endpoints.rst @@ -0,0 +1,240 @@ +.. _Platforms-Historians-Endpoints: + +============================== +Platforms Historians Endpoints +============================== + +Platform Historian endpoints expose functionality related to historians +running on a VOLTTRON platform. + +.. admonition:: Use of Topics + + There is no special meaning to most segments of a topic in the VOLTTRON platform. In the context of + devices, however, the final segment in a full topic denotes a point which can be read or actuated. + Partial topics denote some collection of these point resources. For instance, in the caes of a topic hierarchy + organized as ``:campus/:building/:device/:point``, a topic which is complete up to the ``:device`` level would + yield a single device containing one or more points. A topic complete to the ``:building`` level would include a + set of devices, each containing some set of points. The response to any request containing a full topic will + therefore perform a get or set operation, while a partial topic will typically return a list of routes to + further sub-topics (unless it is explicitly requested that an operation be performed on multiple + points). + + Several methods are available to refine the list of topics: + + Topic Wildcards: + The ``-`` character may be used alone to represent any value for a segment: ``/:campus/-/:device`` + will match all devices with the name :device on the :campus in any building. It is not possible to + use ``-`` as a wildcard within a segment containing other characters: ``/campus/foo-bar/:device`` + will only match a building called “foo-bar”, not one called “foobazbar”. + + Topic-Filtering Query Parameters: + - ``tag`` (default=null): + Filter the result by the provided tag. (This requires that the tagging service be + running and configured.) + - ``regex`` (default=null): + Filter the result by the provided regular expression. The raw regular expression + should follow python re syntax, but must be url-encoded within the query-string. + +.. attention:: + All endpoints in this tree require authorization using a JWT bearer access token provided by the + ``POST /authenticate`` or ``PUT /authenticate`` endpoints. +-------------- + +GET /platforms/:platform/historians +=================================== + +Retrieve routes to historians on the platform, where each historian is listed by its VIP identity. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +- **With valid BEARER token on success:** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "": "/vui/platforms/:platform/historians/:historian", + "": "/vui/platforms/:platform/historians/:historian" + } + +- **With valid BEARER token on failure:** ``400 Bad Request`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +GET /platforms/:platform/historians/:historian +============================================== + +Retrieve routes for an historian. The only currently supported result is the "topics" endpoint. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +- **With valid BEARER token on success:** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "topics": "/vui/platforms/:platform/historians/:historian/topics" + } + +- **With valid BEARER token on failure:** ``400 Bad Request`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "error": "" + } + +- **With invalid BEARER token:** ``401 Unauthorized`` + +-------------- + +GET /platforms/:platform/historians/:historian/topics/:topic +============================================================ + +Query data for a topic. If no topic, or a parital topic is provided, the output will be a JSON object containing routes +to additional sub-topics matching the provided partial topic. If a full topic is provided, or if the read-all query +parameter is passed, the response will contain data and/or metadata about any points indicated by the topic. +In addition to the tag and regex query parameters described in the Use of Topics section above, the following query +parameters are accepted: + +- ``read-all`` (default=false): + If true, the response will return entries for every point. These will be a set of JSON objects + with `route`, `writability`, and `value` unless the result is further filtered by the + corresponding query parameters. + +- ``routes`` (default=true): + If true, the result will include the route to the query. + +- ``values`` (default=true): + If true, the result will include the value of the query. + +Several query parameters may also be used to refine the results: + +- start (default=null): + Datetime of the start of the query. + +- end (default=null): + Datetime of the end of of the query. + +- skip (default=null): + Skip this number of results (for pagination). + +- count (default=null): + Return at maximum this number of results (for pagination). + +- order (default=null): + “FIRST_TO_LAST” for ascending time stamps, “LAST_TO_FIRST” for + descending time stamps. + +.. attention:: + Due to current limitations of the VOLTTRON historian, meta-data about the queried data is only returned when a + single topic has been queried. Where multiple topics are selected, the meta-data field will not be present in the + result. + +Request: +-------- + +- Authorization: ``BEARER `` + +Response: +--------- + +- **With valid BEARER token on success (single topic):** ``200 OK`` + + - Content Type: ``application/json`` + + - Body: + + .. code-block:: javascript + + { + "Campus/Building1/Fake2/SampleWritableFloat1": { + "value": [ + ["", ], + ["", ], + ["", ] + ], + "metadata": { + "units": "", + "type": "", + "tz": "