Skip to content

Latest commit

 

History

History
131 lines (96 loc) · 4.46 KB

platform-endpoints.rst

File metadata and controls

131 lines (96 loc) · 4.46 KB
Raw

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:

  • Agents <Platforms-Agents-Endpoints>: Endpoints pertaining to a specific agent (e.g. RPC)
  • Devices <Platforms-Devices-Endpoints>: Endpoints for discovering, getting, and setting data about the current state of devices on the platform.
  • Historians <Platforms-Historians-Endpoints>: Endpoints for querying data from historians.
  • PubSub <Platforms-Pubsub-Endpoints>: Endpoints for subscription and publication to message bus topics.
  • Status <Platforms-Status-Endpoints>: 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 <jwt_access_token>

Response:

  • With valid BEARER token on success: 200 OK
    • Content Type: application/json

    • Body:

      {
    "route_options": {
        "<platform1>": "/platforms/<platform1>",
        "<platform2>": "/platforms/<platform2>"
    }
}
  • With valid BEARER token on failure: 400 Bad Request
    • Content Type: application/json

    • Body:

      {
 "error": "<Error Message>"
}

* 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: agents <Platforms-Agents-Endpoints>, devices <Platforms-Devices-Endpoints>, historians <Platforms-Historians-Endpoints>, pubsub <Platforms-Pubsub-Endpoints> and status <Platforms-Status-Endpoints>.

Request:

  • Authorization: BEARER <jwt_access_token>

Response:

  • With valid BEARER token on success: 200 OK
    • Content Type: application/json

    • Body:

      {
    "route_options": {
        "<endpoint1_name>": "/platforms/:platform/<endpoint1_name>",
        "<endpoint2_name>": "/platforms/:platform/<endpoint2_name>"
    }
}
  • With valid BEARER token on failure: 400 Bad Request
    • Content Type: application/json

    • Body:

      {
 "error": "<Error Message>"
}
  • With invalid BEARER token: 401 Unauthorized

Agents <platforms/agent-endpoints> Configs <platforms/config-endpoints> Devices <platforms/device-endpoints> Health <platforms/health-endpoints> Historians <platforms/historian-endpoints> Pubsub <platforms/pubsub-endpoints> Status <platforms/status-endpoints>