<commit_before>Go Metrics HTTP API
===================

Contents
--------

- :ref:`response-format-overview`
- :ref:`metric-types`
- :ref:`api-authentication`
- :ref:`api-methods`

    - :http:get:`/api/metrics`

.. _response-format-overview:

Response Format Overview
------------------------

Successful responses to GET requests will contain the requested data in json
format.

**Example response (success response)**:

.. sourcecode:: http

    HTTP/1.1 200 OK
    {
        ...
    }

Errors are returned with the relevant HTTP error code and a json object
containing ``status_code``, the HTTP status code, and ``reason``, the reason
for the error.

**Example response (error response)**:

.. sourcecode:: http

    HTTP/1.1 400 Bad Request
    {
        "status_code": 400,
        "reason": "Bad Request"
    }


.. _metric-types

Metric Types
------------

Account Metrics
~~~~~~~~~~~~~~~

Account metrics are metrics relevant to a particular account, but not
necessarily relevant to a particular conversation in the account. All metrics
published via Vumi Go javascript sandbox applications are account metrics. Account metric names take the form ``stores.<store_name>.<metric_name>.<agg_method>``:

    - ``store_name``: the namespace used for publishing the metrics (e.g.
      ``default``). For javascript sandbox applications, the store name matches
      the configured name for the app in the conversation config unless
      configured otherwise.
    - ``metric_name``: the name of the metric (e.g. ``questions_completed``).
    - ``agg_method``: the aggregation method used to publish metric values (e.g.
      ``last``).


Conversation Metrics
~~~~~~~~~~~~~~~~~~~~

Conversation metrics are metrics relevant only to a particular conversation,
for example, the total messages sent in the conversation. Conversation metric
names take the form ``conversations.<conv_id>.<metric_name>.<agg_method>``:

    - ``conv_id``: the UUID for the conversation.
    - ``metric_name``: the name of the metric (e.g. ``messages_sent``).
    - ``agg_method``: the aggregation method used to publish metric values (e.g.
      ``last``).

*Note*: At the time of writing, conversation metrics are not yet ready for use.


.. _api-authentication:

API Authentication
------------------

Authentication is done using an OAuth bearer token.

**Example request**:

.. sourcecode:: http

    GET /api/contacts/ HTTP/1.1
    Host: example.com
    Authorization: Bearer auth-token

**Example response (success)**:

.. sourcecode:: http

    HTTP/1.1 200 OK

**Example response (failure)**:

.. sourcecode:: http<commit_msg>Fix copy-paste error in docs<commit_after>Go Metrics HTTP API
===================

Contents
--------

- :ref:`response-format-overview`
- :ref:`metric-types`
- :ref:`api-authentication`
- :ref:`api-methods`

    - :http:get:`/api/metrics`

.. _response-format-overview:

Response Format Overview
------------------------

Successful responses to GET requests will contain the requested data in json
format.

**Example response (success response)**:

.. sourcecode:: http

    HTTP/1.1 200 OK
    {
        ...
    }

Errors are returned with the relevant HTTP error code and a json object
containing ``status_code``, the HTTP status code, and ``reason``, the reason
for the error.

**Example response (error response)**:

.. sourcecode:: http

    HTTP/1.1 400 Bad Request
    {
        "status_code": 400,
        "reason": "Bad Request"
    }


.. _metric-types

Metric Types
------------

Account Metrics
~~~~~~~~~~~~~~~

Account metrics are metrics relevant to a particular account, but not
necessarily relevant to a particular conversation in the account. All metrics
published via Vumi Go javascript sandbox applications are account metrics. Account metric names take the form ``stores.<store_name>.<metric_name>.<agg_method>``:

    - ``store_name``: the namespace used for publishing the metrics (e.g.
      ``default``). For javascript sandbox applications, the store name matches
      the configured name for the app in the conversation config unless
      configured otherwise.
    - ``metric_name``: the name of the metric (e.g. ``questions_completed``).
    - ``agg_method``: the aggregation method used to publish metric values (e.g.
      ``last``).


Conversation Metrics
~~~~~~~~~~~~~~~~~~~~

Conversation metrics are metrics relevant only to a particular conversation,
for example, the total messages sent in the conversation. Conversation metric
names take the form ``conversations.<conv_id>.<metric_name>.<agg_method>``:

    - ``conv_id``: the UUID for the conversation.
    - ``metric_name``: the name of the metric (e.g. ``messages_sent``).
    - ``agg_method``: the aggregation method used to publish metric values (e.g.
      ``last``).

*Note*: At the time of writing, conversation metrics are not yet ready for use.


.. _api-authentication:

API Authentication
------------------

Authentication is done using an OAuth bearer token.

**Example request**:

.. sourcecode:: http

    GET /api/metrics/ HTTP/1.1
    Host: example.com
    Authorization: Bearer auth-token

**Example response (success)**:

.. sourcecode:: http

    HTTP/1.1 200 OK

**Example response (failure)**:

.. sourcecode:: http
{'fraction_non_alphanumeric': 0.14713740458015268, 'fraction_numerical': 0.007633587786259542, 'mean_word_length': 3.288870703764321, 'pattern_counts': {'":': 4, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, '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': '2583096', 'n_tokens_mistral': 1480, 'n_tokens_neox': 1403, 'n_words': 551}