Entity
======

.. code-block:: http

    /api/repositories/{repository}/entities/{entity}

.. csv-table::
    :header: Parameter, Type, Purpose
    :widths: 20, 20, 60
    :stub-columns: 1

    repository, string, The name of the :doc:`repository` to access
    entity, int, The ID of the entity to view


.. _e_show:

Show
~~~~

.. http:get:: /api/repositories/(string:repository)/entities/(int:entityID)
    :synopsis: List metadata for an entity

    Get the metadata for an entity.

.. code-block:: http

    GET /api/repositories/jupiter/entities/1 HTTP/1.1
    Accept: application/json

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    500, Server error

The response is a JSON string containing two values:

+ Columns_
+ Rows_

Columns
-------

The columns value is a JSON array describing the columns that make up the data rows.

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

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

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

.. code-block:: json

    {
        "columns": [
            {
                "columnisedName": "_col0",
                "humanisedName": "Metadata",
                "description": "The name of the metadata statistic"
            },
            {
                "columnisedName": "_col1",
                "humanisedName": "Value",
                "description": "The value of the metadata statistic"
            },
            {
                "columnisedName": "_col2",
                "humanisedName": "Description",
                "description": "A description of the metadata statistic"
            }
        ]
    }

Rows
----

The rows value is a JSON array. Each element consists of one or 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); appears only in rows having appropriate metadata available

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": [
                    "Rows",
                    "9999",
                    "The number of loaded rows"
                ],
                "metadata": {
                    "url": "/api/repositories/test/entities/2/rows"
                }
            },
            {
                "dataRow": [
                    "Values",
                    "39642",
                    "The number of distinct values loaded (across all attributes)"
                ]
            },
			...
        ]
    }


.. _e_load:

Load
~~~~

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)
    :synopsis: Load data to an entity

    Load data to an entity.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1 HTTP/1.1
    Content-Type: application/json

    {
        "command": "load",
        "data": {
            "jobName": "my delimited load",
            "scheduleNow": "0",
            "scheduleTime": "2016-05-05 17:30:45"
        }
    }

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    204, No error
    400, Invalid data passed with request
    500, Server error

The request packet must contain the ``command`` and ``data`` elements. The ``options`` element is not required.

The following table shows which fields are required in ``data`` element:

.. csv-table::
    :header: Field, Required
    :widths: 20, 30

    jobName, Yes
    scheduleNow, Yes
    scheduleTime, No (if scheduleNow is 1) / Yes (if scheduleNow is 0)

``scheduleNow`` field can be formatted as follows:

.. csv-table::
    :header: Value, Description
    :widths: 10, 75

    1, Schedule the job immediately
    0, Schedule the job at a given date and time (requires ``scheduleTime`` field)

``scheduleTime`` field can be formatted as follows:

.. csv-table::
    :header: Value, Example
    :widths: 50, 75

    YYYY-Month-DD HH:MM:SS, 2016-JANUARY-01 10:30:45
    YYYY/Month/DD HH:MM:SS, 2016/JANUARY/01 10:30:45
    YYYY-Mon-DD HH:MM:SS, 2016-JAN-01 10:30:45
    YYYY/Mon/DD HH:MM:SS, 2016/JAN/01 10:30:45
    YYYY-MM-DD HH:MM:SS, 2016-01-01 10:30:45
    YYYY/MM/DD HH:MM:SS, 2016/01/01 10:30:45


If the command is successful, the response will return the url link to a scheduled job as follows:

.. code-block:: json

    {
      "url": "/api/repositories/jupiter/scheduler/1"
    }


.. _e_edit:

Edit
~~~~

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)
    :synopsis: Edit an entity

    Edit an entity.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1 HTTP/1.1
    Content-Type: application/json

    {
        "command": "edit",
        "data": {
            "name": "entity name",
            "description": "entity description"
        }
    }

The request packet must contain the ``command`` and ``data`` elements.

.. csv-table::
    :header: Key, Purpose
    :widths: 30, 70

    name, The new name of the entity
    description, The new description for the entity

The ``name`` field is required. The ``description`` field is optional.

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    400, Invalid data passed with request
    500, Server error


If the command is successful, the response will return the url link to an updated entity as follows:


.. code-block:: json

    {
      "url": "/api/repositories/jupiter/entities/1"
    }



.. _e_delete:

Delete
~~~~~~~

.. http:post:: /api/repositories/(string:repository)/entities
    :synopsis: Delete one or more entities

    Delete one or more entities.

.. code-block:: http

    DELETE /api/repositories/jupiter/entities HTTP/1.1
    Content-Type: application/json

    {
        "command": "delete",
        "data": {
            "entityId": ["198", "199"]
        }
    }

The request packet must contain the ``command`` and ``data`` elements.

.. csv-table::
    :header: Key, Purpose
    :widths: 30, 70

    entityId, A list of entity IDs.

To delete only one entity, provide only 1 entity ID:

.. code-block:: json

    {
        "command": "delete",
        "data": {
            "entityId": ["200"]
        }
    }

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    400, Invalid data passed with request
    500, Server error


If the command is successful, the response will return the url link to the scheduled job:


.. code-block:: json

    {
      "url": "/api/repositories/jupiter/scheduler/136"
    }