.. CentralService API Documentation


Buildings
#########

All the buildings that are present within the deployment of BuildingDepot are defined here. When adding a new building a BuildingTemplate has to be selected which defines the structure of this building. The tags that are available to be assigned to this building are dependent on the BuildingTemplate. Tags can be selected and the values for each of them can be specified here. Each tag can have multiple values specified for it. Building can be defined in the CentralService at http://www.example.com:81/api/building.

Create a new Building
*********************

This request creates a new Building with name, description and building template to be used in the building specified by the user.

.. http:post:: /api/building

   :json string name: Name of the Building
   :json string description: Description for the Building
   :json string template: Name of a BuildingTemplate

   :returns:
      * **success** `(string)` -- Returns 'True' if data is posted successfully otherwise 'False'
      * **error** `(string)` -- An additional value that will be present only if the request fails specifying the cause for failure
   :status 200: Success
   :status 401: Unauthorized Credentials

.. compound::

   **Example request**:

   .. sourcecode:: http

      POST /api/building HTTP/1.1
      Accept: application/json; charset=utf-8

      {
        "data":{
            "name":"Test_Building",
            "description":"New Building",
            "template":"Test_Building_Template"
        }
      }

   **Example response** (for success):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "True"
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": " BuildingTemplate does not exist"
      }

      {
        "success": "False",
        "error": " Missing parameters"
      }

      {
        "success": "False",
        "error": " Missing data"
      }

Get Building Details
********************
This request retrieves name, description and template to used in the building specified in the request.

.. http:get:: /api/building/<name>

   :param string name: Name of the Building

   :returns:
      * **success** `(string)` -- Returns 'True' if data is retrieved successfully otherwise 'False'
      * **name** `(string)` -- Name of the Building
      * **description** `(string)` -- Description for the Building
      * **template** `(string)` --  BuildingTemplate assigned for the Building.

   :status 200: Success
   :status 401: Unauthorized Credentials


.. compound::

   **Example request**:

   .. sourcecode:: http

      GET /api/building/Test_Building HTTP/1.1
      Accept: application/json; charset=utf-8

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {   "success": "True",
          "name": "Test_Building",
          "description":"New Building",
          "template": "Test_Building_Template"
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": " Building does not exist"
      }

Delete Building
***************

This request deletes the requested Building and the template assigned to it.

.. http:delete:: /api/building/<name>


   :param string name: Name of the Building

   :returns:
      * **success** `(string)` -- Returns 'True' if the Building is successfully deleted otherwise 'False'

   :status 200: Success
   :status 401: Unauthorized Credentials

.. compound::

   **Example request**:

   .. sourcecode:: http

      DELETE /api/building/Test_Building HTTP/1.1
      Accept: application/json; charset=utf-8

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "True"
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": " Building does not exist"
      }

      {
        "success": "False",
        "error": " Building is in use"
      }

Create a new Building Tag
*************************

This request creates a new Tag Value pair for a Building

.. http:post:: /api/building/<building_name>/tags

   :param string building_name: Name of the Building

   :JSON Parameters:
      * **data** `(dictionary)` -- Contains the information of the tag to be added to the sensor.
          * **name** `(string)` -- Name of the Tag Type
          * **value** `(string)` -- Value for the Tag Type
          * **parents** `(list)` -- List of tags
              * **name** `(string)` -- Name of the Tag Type
              * **value** `(string)` -- Value for the Tag Type

   :returns:
      * **success** `(string)` -- Returns 'True' if data is posted successfully otherwise 'False'
      * **error** `(string)` -- An additional error information that will be present only if the request fails informing the cause for failure
   :status 200: Success
   :status 401: Unauthorized Credentials

.. compound::

   **Example request**:

   .. sourcecode:: http

      POST /api/building/WeanHall/tags HTTP/1.1
      Accept: application/json; charset=utf-8

      {
        "data":{
            "name":"corridor",
            "value": 10,
            "parents": [{"name": "floor", "value": "1"}]
        }
      }

   **Example response** (for success):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "True"
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": "One of the buildings does not exist"
      }

      {
        "success": "False",
        "error": " Missing parameters"
      }

      {
        "success": "False",
        "error": " Missing data"
      }

Get Building Tag Details
************************
This request retrieves name, description and template to used in the building specified in the request.

.. http:get:: /api/building/<building_name>/tags

   :param string name: Name of the Building

   :returns:
      * **success** `(string)` -- Returns 'True' if data is retrieved successfully otherwise 'False'
      * **tags** `(list)` -- List of Tags attached to the Building
      * **pairs** `dictionary` -- Available Tagtypes that can be attached to the Building

   :status 200: Success
   :status 401: Unauthorized Credentials

.. compound::

   **Example request**:

   .. sourcecode:: http

      GET /api/building/WeanHall/tags HTTP/1.1
      Accept: application/json; charset=utf-8

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
          "success": "True",
          "pairs": {
                    "Room": [],
                    "corridor": ["floor"],
                    "floor": []
		            },
          "tags": [
                        {  "value": "1",
                           "parents": [],
                           "name": "floor",
                           "can_delete": false
                        },
                        {
                            "value": "10",
                            "parents": [
                                         {
                                            "name": "floor",
                                            "value": "1"
                                            }
                                        ],
                            "name": "corridor",
                            "can_delete": true
                        }
                   ]
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": "One of the buildings does not exist"
      }

      {
        "success": "False",
        "error": " Missing parameters"
      }

Delete Building Tags
********************

This request deletes the requested Building and the template assigned to it.

.. http:delete:: /api/building/<building_name>/tags

   :param string name: Name of the Building

   :JSON Parameters:
      * **data** `(dictionary)` -- Contains the information of the tag to be added to the sensor.
          * **name** `(string)` -- Name of the Tag Type
          * **value** `(string)` -- Value for the Tag Type

   :returns:
      * **success** `(string)` -- Returns 'True' if the Building is successfully deleted otherwise 'False'
      * **error** `(string)` -- An additional error information that will be present only if the request fails informing the cause for failure

   :status 200: Success
   :status 401: Unauthorized Credentials

.. compound::

   **Example request**:

   .. sourcecode:: http

      DELETE /api/building/WeanHall/tags HTTP/1.1
      Accept: application/json; charset=utf-8

      { "data":{
            "name":"corridor",
            "value": "10",
        }
      }

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "True"
      }

   **Example response** (for failure):

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "success": "False",
        "error": " This tag value is being referenced, cannot delete"
      }

      {
        "success": "False",
        "error": "Tag value does not exist"
      }

      {
        "success": "False",
        "error": "Missing data"
      }