Docs: Initial import of Admin API

Converted and slightly modified the original API docs from markdown format.

Change-Id: Id4c742cad483e799e39bd7cfc87e30f50083a7ff

.gitignore

@@ -17,4 +17,3 @@ debian/libra.prerm.debhelper
 debian/libra.substvars
 dist
 doc/html
-doc/api

doc/admin_api/about.rst

@@ -0,0 +1,16 @@
+Description
+===========
+
+Purpose
+-------
+
+The Admin API server listens for REST+JSON connections to interface various
+parts of the LBaaS system and other scripts with the LBaaS database state.
+
+Design
+------
+
+Similar to the main API server it uses an Eventlet WSGI web server frontend
+with Pecan+WSME to process requests.  SQLAlchemy+MySQL is used to access the
+data store.  The main internal difference (apart from the API itself)  is the
+Admin API server doesn't use keystone or gearman.

doc/admin_api/api.rst

@@ -0,0 +1,381 @@
+LBaaS Device API
+================
+
+Description
+-----------
+
+The LBaaS service provides two classes of APIs including a tenant facing
+API and admin API. The admin API is designed for internal usage to allow
+administration of the LBaaS service itself. As part of this, the *Device
+API* allows for managing devices which are the actual load balancer
+devices used by LBaaS.
+
+API Overview
+------------
+
+The device API is not visible to tenants thus it is designed to operate
+on its own HTTPS port which is configurable. The device API only
+supports a JSON resource representation for reading and writing. The API
+is designed as a RESTful API including support of CRUD operations for
+creating, reading, updating and deleting devices.
+
+Base URL and port
+^^^^^^^^^^^^^^^^^
+
+All device API calls run on the same TCP port and require HTTPS for
+access. The specific HTTPS port and certificate are configurable by the
+LBaaS service and will comply with the Cloud security requirements
+including the certificate signing. The API is version'ed such that all
+calls are prefixed with a version URI. For example,
+
+``https://lbaas-service:8889/v1/devices/...``
+
+would access the LBaaS system hosted on lbaas-service, using HTTPS on
+port 8889 using version 1 of the API.
+
+Exceptions
+^^^^^^^^^^
+
+As a RESTful service, the device API can return standard HTTP status
+codes with each request including success and error codes mentioned
+below. In the event a non 200 series status is returned, a JSON
+formatted error body is provided with additional details. The format of
+the JSON error body is as follows:
+
+*Example of a bad request JSON error response body*
+
+::
+
+    {
+       "message":"Bad Request",
+       "details":"device name : lbaas-10.5.251.48 already exists",
+       "code":400
+    }
+
+Base URI
+^^^^^^^^
+
+All LBaaS Device API calls have a common base URI defined as follows:
+
+``<baseURI> = https://<lbaas-system-addr>:<lbaas-device-port>/v1``
+
+-  *lbaas-system-addr* is the system name / address where the LBaaS API
+   service is running.
+
+-  *lbaas-device-port* is the TCP port in which the device service is
+   listening for HTTPS REST requests.
+
+-  */v1/devices* will prefix all REST calls.
+
+Device Data Model
+^^^^^^^^^^^^^^^^^
+
+Device REST calls allow reading and writing device resources represented
+in JSON. The data model for devices is defined as follows:
+
+id
+^^
+
+*id* is an integer representing a unique id for the device. *id* is
+created by the LBaaS service when devices are created. *id* is used to
+reference devices as the REST collection id.
+
+updated
+^^^^^^^
+
+*updated* is a text string representing the last time this device
+resource was updated.
+
+created
+^^^^^^^
+
+*created* is a text string representing when the device was created.
+
+status
+^^^^^^
+
+*status* is a text string representing the status of the device as
+reported by the device to the LBaaS service ( this is done through the
+gearman client / worker interface ). Status values can be 'OFFLINE',
+'ONLINE', 'ERROR'.
+
+address
+^^^^^^^
+
+*address* is the IPv4 or IPV6 address of the device. This is the adress
+which will be used as the loadbalancer's address used by the customer.
+Note, this should be a Nova floating IP address for usage with HAProxy
+on Nova.
+
+name
+^^^^
+
+*name* is the name of the device which is used internally by LBaaS as
+the gearman worker name. Each device name is specified by the pool
+manager and must be unique for each device. The format of the name is
+``lbaas-<version>-<id>`` where ``<version>`` is the gearman worker
+version e.g. *v1* and ``<id>`` is a unique UUID for the name.
+
+loadbalancer
+^^^^^^^^^^^^
+
+*loadbalancer* are references to logical loadbalancers who are using
+this device. This is a list of one or more integers. An empty or zero
+value denotes that this device is not used and is free. Note, if the
+device is not in use, it has no customer loadbalancer config and is in a
+'OFFLINE' state.
+
+type
+^^^^
+
+*type* is a text string describing the type of device. Currently only
+'HAProxy' is supported.
+
+Example of a single device
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    {
+        "id":1,
+        "updated":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "created":"Mon 2012.10.29 at 07:21:48 PM UTC",  
+        "status":"OFFLINE",
+        "address":"15.185.96.125",
+        "name":"lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "loadbalancer":0,
+        "type":"HAProxy"
+    }
+
+Operations
+==========
+
+Get all Devices
+---------------
+
+Get all devices currently defined.
+
+::
+
+    GET <baseURI>/devices
+
+Return Status
+^^^^^^^^^^^^^
+
+200 on success, 500 for internal error
+
+Example
+^^^^^^^
+
+::
+
+    curl -k https://15.185.107.220:8889/v1/devices
+
+Response:
+
+::
+
+    {
+        "devices":[
+            {
+                "id":1,
+                "updated":"Mon 2012.10.29 at 07:21:48 PM UTC",
+                "created":"Mon 2012.10.29 at 07:21:48 PM UTC",
+                "status":"OFFLINE",
+                "address":"15.185.96.125",
+                "name":"lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+                "loadbalancer":0,
+                "type":"HAProxy"
+            }
+        ]
+    }
+
+Get a Device
+------------
+
+Get a specific device.
+
+::
+
+    GET <baseURI>/devices/{deviceId}
+
+Return Status
+^^^^^^^^^^^^^
+
+200 on success, 404 not found, 500 for internal error
+
+Example
+^^^^^^^
+
+::
+
+    curl -k https://15.185.107.220:8889/v1/devices/1
+
+Response:
+
+::
+
+    {
+        "id":1,
+        "updated":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "created":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "status":"OFFLINE",
+        "address":"15.185.96.125",
+        "name":"lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "loadbalancer":0,
+        "type":"HAProxy"
+    }
+
+Create a Device
+---------------
+
+Create a new device will register an already deployed device with the
+LBaaS service. In order to do so, LBaaS will need to know its name and
+address. Returned will be the new device including its *id*.
+
+::
+
+    POST <baseURI>/devices
+
+Return Status
+^^^^^^^^^^^^^
+
+200 on success, 400 bad request, 500 for internal error
+
+Request Body
+^^^^^^^^^^^^
+
+A JSON request body is required for this request.
+
+::
+
+    {
+        "name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "address": "15.185.96.125"
+    }
+
+Example
+^^^^^^^
+
+::
+
+    curl -X POST -H "Content-type:application/json" --data-binary "@device.json" -k https://15.185.107.220:8889/v1/devices
+
+Response:
+
+::
+
+    {
+        "id":1,
+        "updated":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "created":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "status":"OFFLINE",
+        "address":"15.185.96.125",
+        "name":"lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "loadbalancer":0,
+        "type":"HAProxy"
+    }
+
+Delete a Device
+---------------
+
+Delete a device will delete a device from the LBaaS service. Note, this
+call can be dangerous and effect a customers load balancer if it is in
+use. *please use this call with extreme caution!*.
+
+::
+
+    DELETE <baseURI>/devices/{deviceId}
+
+Return Status
+^^^^^^^^^^^^^
+
+204 on success, 400 bad request, 500 for internal error
+
+Example
+^^^^^^^
+
+::
+
+    curl -X POST -k https://15.185.107.220:8889/v1/devices/1
+
+Update a Device
+---------------
+
+Update a device allows changing the address or name of a device. No
+other fields can be changed and will be ignored.
+
+::
+
+    PUT <baseURI>/devices/{deviceId}
+
+Return Status
+^^^^^^^^^^^^^
+
+200 on success, 400 bad request, 500 for internal error
+
+Request Body
+^^^^^^^^^^^^
+
+A JSON request body is required for this request.
+
+::
+
+    {
+        "name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "address": "15.185.96.125"
+    }
+
+Example
+^^^^^^^
+
+::
+
+    curl -X PUT -H "Content-type:application/json" --data-binary "@device.json" -k https://15.185.107.220:8889/v1/devices/1
+
+Response:
+
+::
+
+    {
+        "id":1,
+        "updated":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "created":"Mon 2012.10.29 at 07:21:48 PM UTC",
+        "status":"OFFLINE",
+        "address":"15.185.96.125",
+        "name":"lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
+        "loadbalancer":0,
+        "type":"HAProxy"
+    }
+
+Get Usage of Devices
+--------------------
+
+This call allows obtaining usage summary information for all devices.
+
+::
+
+    GET <baseURI>/devices/usage
+
+Return Status
+^^^^^^^^^^^^^
+
+200 on success, 500 for internal error
+
+Example
+^^^^^^^
+
+::
+
+    curl -k https://15.185.107.220:8889/v1/devices/usage
+
+Response:
+
+::
+
+    {
+        "total": 100,
+        "free" : 50,
+        "taken": 50
+    }
+

doc/admin_api/index.rst

@@ -0,0 +1,8 @@
+Libra Admin API Server
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   api

doc/api/about.rst

@@ -0,0 +1,16 @@
+Description
+===========
+
+Purpose
+-------
+
+The API server listens for REST+JSON connections to interface the user with
+the LBaaS system.  Its API is based on the Atlas API with a few slight
+modifications.
+
+Design
+------
+
+It is designed to use Eventlet WSGI web server frontend and Pecan+WSME to
+process the requests.  SQLAlchemy+MySQL is used to store details of the load
+balancers and Gearman is used to communicate to the workers.

doc/api/index.rst

@@ -0,0 +1,8 @@
+Libra API Server
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   api

doc/index.rst

@@ -8,4 +8,6 @@ Load Balancer as a Service Device Tools
    worker/index
    pool_mgm/index
    statsd/index
+   api/index
+   admin_api/index
    config