Standard Response
=================

A number of endpoints will return a response that shares a common structure.

The response is a JSON string containing three values:

+ Metadata_
+ Columns_
+ Rows_

Metadata
~~~~~~~~

The metadata value is a JSON list containing the following keys:

.. csv-table::
    :header: Key, Description
    :widths: 20, 80

    viewName, The name of the view used to retrieve the requested data
    pageStart, The data item the page starts at
    dataSize, The number of data rows returned
    totalCount, The total number of rows available

.. code-block:: json

    {
        "metadata": {
            "viewName": "a_view",
            "pageStart": "1",
            "dataSize": "10",
            "totalCount": "25"
        }
    }

Columns
~~~~~~~

The columns value is a JSON array describing the columns that make up the view referenced in ``viewName`` (in the Metadata_).

Each element in the array is a JSON list containing the following keys:

.. csv-table::
    :header: Key, Description
    :widths: 20, 80

    humanisedName, The column name for human consumption
    columnisedName, The column name for computer consumption
    description, Description of the column within the view

.. code-block:: json

    {
        "columns": [
            {
                "humanisedName": "Human column name",
                "columnisedName": "_human_column_name",
                "description": "An example of a column element"
            }
        ]
    }

Rows
~~~~

.. _internal_json_response:

Internal JSON Response
----------------------

The rows value is a JSON array; the length of the array is determined by the ``dataSize`` value in the Metadata_.

Each element consists of a list of two values:

.. csv-table::
    :header: Key, Desciption
    :widths: 20, 80

    dataRow, An array containing the data for the row; will have as many elements as there are Columns_
    metadata, A JSON list containing metadata for the data row (see below)

The row metadata contains the following value:

.. csv-table::
    :header: Key, Description
    :widths: 20, 80

    url, The URL to get the data item

.. code-block:: json

    {
        "rows": [
            {
                "dataRow":[
                    "Data",
                    "from",
                    "the",
                    "row"
                ],
                "metadata": {
                    "url": "/for/the/row"
                }
            }
        ]
    }


.. _external_json_response:

External JSON Response
----------------------

The rows value is a JSON array; the length of the array is determined by the ``dataSize`` value in the Metadata_.

When external JSON format is selected, the row data will be returned as key/value pairs as shown below. The data shown below is just an example, the actual contents of the data rows are particular to each endpoint.

Each element consists of a list of data values and a metadata:

.. csv-table::
    :header: Key, Desciption
    :widths: 20, 80

    dataValues, List of data values for the row; will have as many elements as there are Columns_
    metadata, Metadata for the data row (see below)

The row metadata contains the following value:

.. csv-table::
    :header: Key, Description
    :widths: 20, 80

    url, The URL to get the data item

.. code-block:: json

    {
        "rows": [
            {
                "Name": "Input",
                "Project Base": "1",
                "Project Internal": "0",
                "Ref": "1",
                "Schema Name": "input",
                "metadata": {
                    "url": "/for/the/row"
                }
            }
        ]
    }