<commit_before>===============================================
VOLTTRON Central Web Services Api Documentation
===============================================

VOLTTRON Central is meant to be the hub of communcation within a cluster of
VOLTTRON instances.  Through it's api one can control platforms at different
locations throughout an organization.  This document describes the json api
exposed via the VOLTTRON web service module.

Expectation of API
==================
* All communication with the api will be done through a post request.
* All messages sent to the api will be according to `jsonrpc-2.0 protocol
<http://www.jsonrpc.org/specification>`_.

Messages
========

Register A Volttron Platform Instance (Using Discovery)
    .. code-block:: Python

        # POST /api/jsonrpc<commit_msg>updated rst api documentation to include json-rpc specifics.'<commit_after>===============================================
VOLTTRON Central Web Services Api Documentation
===============================================

VOLTTRON Central (VC) is meant to be the hub of communcation within a cluster of
VOLTTRON instances. VC exposes a
`JSON-RPC 2.0 <http://www.jsonrpc.org/specification/>`_ based api that allows
a user to control multple instances of VOLTTRON.


Why JSON-RPC
============

SOAP messaging is unfriendly to many developers, especially those wanting to
make calls in a browser from AJAX environment. We have therefore have
implemented a JSON-RPC API capability to VC, as a more JSON/JavaScript
friendly mechanism.


How the API is Implemented
==========================

* All calls are made through a POST.
* All calls (not including the call to authenticate) will
  include an authorization token (a json-rpc extension).

JSON-RPC Request Payload
========================

All posted JSON payloads will look like the following block:

.. code-block:: JSON

    {
        "jsonrpc": "2.0",
        "method": "method_to_invoke",
        "params": {
            "param1name": "param1value",
            "param2name": "param2value"
        },
        "id": "unique_message_id",
        "authorization": "server_authorization_token"
    }

As an alternative, the params can be an array as illistrated by the following:

.. code-block:: JSON

    {
        "jsonrpc": "2.0",
        "method": "method_to_invoke",
        "params": [
            "param1value",
            "param2value"
        ],
        "id": "unique_message_id",
        "authorization": "server_authorization_token"
    }

For full documentation of the Request object please see section 4 of the
`JSON-RPC 2.0 <http://www.jsonrpc.org/specification/>`_ specification.

JSON-RPC Response Payload
=========================

All responses shall have either an either an error response or a result
response.  The result key shown below can be a single instance of a json
type, an array or a JSON object.

A result response will have the following format:

.. code-block:: JSON

    {
        "jsonrpc": "2.0",
        "result": "method_results",
        "id": "sent_in_unique_message_id"
    }

An error response will have the following format:

.. code-block:: JSON

    {
        "jsonrpc": "2.0",
        "error": {
            "code": "standard_code_or_extended_code",
            "message": "error message"
        }
        "id": "sent_in_unique_message_id_or_null"
    }

For full documenation of the Response object please see section 5 of the
`JSON-RPC 2.0 <http://www.jsonrpc.org/specification/>`_ specification.

JSON-RPC Data Objects
=====================

.. csv-table:: Platform
    :header: "Key", "Type", "Value"
    :widths: 10, 10, 40

    "uuid", "string", "A unique identifier for the platform."
    "name", "string", "A user defined string for the platform."

JSON-RPC API Methods
====================

.. csv-table:: Methods
    :header: "method", "parameters", "returns"
    :widths: 10, 10, 40

    "get_authentication", "(username, password)", "authentication token"



Messages
========

Register A Volttron Platform Instance (Using Discovery)
    .. code-block:: Python

        # POST /api/jsonrpc
{'fraction_non_alphanumeric': 0.16796684544124818, 'fraction_numerical': 0.008776206728425159, 'mean_word_length': 3.523704520396913, 'pattern_counts': {'":': 20, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3012934', 'n_tokens_mistral': 1159, 'n_tokens_neox': 1087, 'n_words': 425}