From 0954c5f7ae1f18d07662d578eaf015225c5fb1e7 Mon Sep 17 00:00:00 2001
From: akhilbatra898 <akhil.batra@research.iiit.ac.in>
Date: Sat, 25 Mar 2017 03:54:47 +0530
Subject: Add API docs

  - Add developer guide for API
  - Add user guide for API
  - Add api to user guide doctree

JIRA: QTIP-234

Change-Id: Id388f82c52e31b3c75599ab846e64431be8083b7
Signed-off-by: akhilbatra898 <akhil.batra@research.iiit.ac.in>
(cherry picked from commit 6cd177d400b3462cd6c6b251f9135b45c33dfbb8)
---
 docs/testing/user/userguide/api.rst   | 91 +++++++++++++++++++++++++++++++++++
 docs/testing/user/userguide/index.rst |  1 +
 2 files changed, 92 insertions(+)
 create mode 100644 docs/testing/user/userguide/api.rst

(limited to 'docs/testing/user/userguide')

diff --git a/docs/testing/user/userguide/api.rst b/docs/testing/user/userguide/api.rst
new file mode 100644
index 00000000..080fef5f
--- /dev/null
+++ b/docs/testing/user/userguide/api.rst
@@ -0,0 +1,91 @@
+**************
+QTIP API Usage
+**************
+
+QTIP consists of a number of benchmarking tools or metrics, grouped under QPI's. QPI's map to the different
+components of an NFVI ecosystem, such as compute, network and storage. Depending on the type of application,
+a user may group them under plans.
+
+QTIP API provides a RESTful interface to all of the above components. User can retrieve list of plans, QPIs
+and metrics and their individual information.
+
+
+Running
+=======
+
+After installing QTIP. API server can be run using command ``qtip-api`` on the local machine.
+
+All the resources and their corresponding operation details can be seen at ``/v1.0/ui``,
+on hosting server(``0.0.0.0:5000`` for the local machine).
+
+The whole API specification in json format can be seen at ``/v1.0/swagger.json``.
+
+The data models are given below:
+
+  * Plan
+  * Metric
+  * QPI
+
+Plan::
+
+  {
+    "name": <plan name>,
+    "description": <plan profile>,
+    "info": <{plan info}>,
+    "config": <{plan configuration}>,
+    "QPIs": <[list of qpis]>,
+  },
+
+Metric::
+
+  {
+    "name": <metric name>,
+    "description": <metric description>,
+    "links": <[links with metric information]>,
+    "workloads": <[cpu workloads(single_cpu, multi_cpu]>,
+  },
+
+QPI::
+
+  {
+    "name": <qpi name>,
+    "description": <qpi description>,
+    "formula": <formula>,
+    "sections": <[list of sections with different metrics and formulaes]>,
+  }
+
+The API can be described as follows
+
+Plans:
+
+ +--------+----------------------------+-----------------------------------------+
+ | Method | Path                       | Description                             |
+ +========+============================+=========================================+
+ | GET    | /v1.0/plans                | Get the list of of all plans            |
+ +--------+----------------------------+-----------------------------------------+
+ | GET    | /v1.0/plans/{name}         | Get details of the specified plan       |
+ +--------+----------------------------+-----------------------------------------+
+
+Metrics:
+
+ +--------+----------------------------+-----------------------------------------+
+ | Method | Path                       | Description                             |
+ +========+============================+=========================================+
+ | GET    | /v1.0/metrics              | Get the list of all metrics             |
+ +--------+----------------------------+-----------------------------------------+
+ | GET    | /v1.0/metrics/{name}       | Get details of specified metric         |
+ +--------+----------------------------+-----------------------------------------+
+
+QPIs:
+
+ +--------+----------------------------+-----------------------------------------+
+ | Method | Path                       | Description                             |
+ +========+============================+=========================================+
+ | GET    | /v1.0/qpis                 | Get the list of all QPIs                |
+ +--------+----------------------------+-----------------------------------------+
+ | GET    | /v1.0/qpis/{name}          | Get details of specified QPI            |
+ +--------+----------------------------+-----------------------------------------+
+
+
+*Note:*
+    *running API with connexion cli does not require base path (/v1.0/) in url*
diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst
index 96d077c0..04a12f08 100644
--- a/docs/testing/user/userguide/index.rst
+++ b/docs/testing/user/userguide/index.rst
@@ -13,4 +13,5 @@ QTIP User Guide
 
    overview.rst
    cli.rst
+   api.rst
    qpi-compute.rst
-- 
cgit 1.2.3-korg