================
Tricircle API v1
================
This API describes the ways of interacting with Tricircle service via
HTTP protocol using Representational State Transfer(ReST).

Application Root [/]
====================
Application Root provides links to all possible API methods for Tricircle. URLs
for other resources described below are relative to Application Root.

API v1 Root [/v1/]
==================
All API v1 URLs are relative to API v1 root.

Pod [/pods/{pod_id}]
=======================
A pod represents a region in Keystone. When operating a pod, Tricircle
decides the correct endpoints to send request based on the region of the pod.
Considering the 2-layers architecture of Tricircle, we also have 2 kinds of
pods: top pod and bottom pod. A pod has the following attributes:

- pod_id
- pod_name
- pod_az_name
- dc_name
- az_name


**pod_id** is automatically generated when creating a site.

**pod_name** is specified by user but **MUST** match the region name
registered in Keystone. When creating a bottom pod, Tricircle automatically
creates a host aggregate and assigns the new availability zone id to

**az_name**. When **az_name** is empty, that means this pod is top region,
no host aggregate will be generated. If **az_name** is not empty, that means
this pod will belong to this availability zone. Multiple pods with same
**az_name** means that these pods are under same availability zone.

**pod_az_name** is the az name in the bottom pod, it could be empty, if empty,
then no az parameter will be added to the request to the bottom pod. If the
**pod_az_name** is different than **az_name**, then the az parameter will be
replaced to the **pod_az_name** when the request is forwarded to regarding
bottom pod.

**dc_name** is the name of the data center where the pod is located.

URL Parameters
--------------
- pod_id: Pod id

Models
------
::

    {
        "pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
        "pod_name": "pod1",
        "pod_az_name": "az1",
        "dc_name": "data center 1",
        "az_name": "az1"
    }

Retrieve Pod List [GET]
------------------------
- URL: /pods
- Status: 200
- Returns: List of Pods

Response
::

    {
        "pods": [
            {
                "pod_id": "f91ca3a5-d5c6-45d6-be4c-763f5a2c4aa3",
                "pod_name": "RegionOne",
            },
            {
                "pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
                "pod_name": "pod1",
                "pod_az_name": "az1",
                "dc_name": "data center 1",
                "az_name": "az1"
            }
        ]
    }

Retrieve a Single Pod [GET]
----------------------------
- URL: /pods/pod_id
- Status: 200
- Returns: Pod

Response
::

    {
        "pod": {
           "pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
           "pod_name": "pod1",
           "pod_az_name": "az1",
           "dc_name": "data center 1",
           "az_name": "az1"
        }
    }

Create a Pod [POST]
--------------------
- URL: /pods
- Status: 201
- Returns: Created Pod

Request (application/json)
::

    # for the pod represent the region where the Tricircle is running
    {
        "pod": {
           "pod_name": "RegionOne",
        }
    }

    # for the bottom pod which is managed by Tricircle
    {
        "pod": {
           "pod_name": "pod1",
           "pod_az_name": "az1",
           "dc_name": "data center 1",
           "az_name": "az1"
        }
    }

Response
::

    # for the pod represent the region where the Tricircle is running
    {
        "pod": {
           "pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
           "pod_name": "RegionOne",
           "pod_az_name": "",
           "dc_name": "",
           "az_name": ""
        }
    }

    # for the bottom pod which is managed by Tricircle
    {
        "pod": {
           "pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
           "pod_name": "pod1",
           "pod_az_name": "az1",
           "dc_name": "data center 1",
           "az_name": "az1"
        }
    }