From d6640491fe1e0820aa6cc267c8aba2d731b4e028 Mon Sep 17 00:00:00 2001
From: "Kali Kaneko (leap communications)" <kali@leap.se>
Date: Mon, 12 Dec 2016 02:25:56 +0100
Subject: [docs] improve documentation of the API, add some examples

---
 docs/conf.py             |  7 ++++-
 docs/core/index.rst      | 78 +++++++++++++++++++++++++++++++++++++++++++++++-
 pkg/requirements-dev.pip |  2 ++
 3 files changed, 85 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 0339aca..04651b0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -121,7 +121,12 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+# html_theme = 'alabaster'
+
+import sphinx_rtd_theme
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/docs/core/index.rst b/docs/core/index.rst
index 9740744..bd70d36 100644
--- a/docs/core/index.rst
+++ b/docs/core/index.rst
@@ -71,6 +71,14 @@ each one. For details click on the resource name.
 | ``POST`` :ref:`cmd_keys_export`   | Export keys                     |
 +-----------------------------------+---------------------------------+
 
+.. _cmd_parameters:
+
+Passing parameters
+------------------
+
+In all the cases that need data passed as parameter, those will be passed as
+JSON-encoded data to the POST.
+
 .. _cmd_core_version:
 
 /core/version
@@ -79,6 +87,21 @@ each one. For details click on the resource name.
 
   Get Bitmask Core Version Info
 
+  **Example request**::
+
+        curl -X POST localhost:7070/API/core/version 
+ 
+  **Example response**::
+
+   {
+      "error": null,
+      "result":
+          {
+             "version_core": "0.9.3+185.g59ee6c29.dirty"
+          }
+   }
+
+
 .. _cmd_core_stats:
 
 /core/stats
@@ -125,7 +148,60 @@ each one. For details click on the resource name.
 -----------------------
 **POST /bonafide/provider/read**
 
-  Get info bout a given provider.
+  Get info about a given provider.
+
+  **Example request**::
+
+  curl -X POST localhost:7070/API/bonafide/provider/read -d '["dev.bitmask.net"]' 
+
+ 
+  **Example response**::
+
+   {
+   "error": null,         
+        "result": {
+        "api_uri": "https://api.dev.bitmask.net:4430",
+        "api_version": "1",          
+        "ca_cert_fingerprint": "SHA256: 0f17c033115f6b76ff67871872303ff65034efe7dd1b910062ca323eb4da5c7e",
+        "ca_cert_uri": "https://dev.bitmask.net/ca.crt",
+        "default_language": "es",
+        "description": {               
+            "en": "Bitmask is a project of LEAP",
+        }, 
+        "domain": "dev.bitmask.net",
+        "enrollment_policy": "open",
+        "languages": [
+            "es"
+        ],
+        "name": {
+            "en": "Bitmask"
+        },
+        "service": {
+            "allow_anonymous": false,
+            "allow_free": true,
+            "allow_limited_bandwidth": false,
+            "allow_paid": false,
+            "allow_registration": true,
+            "allow_unlimited_bandwidth": true,
+            "bandwidth_limit": 102400,
+            "default_service_level": 1,
+            "levels": {
+                "1": {
+                    "description": "Please donate.",
+                    "name": "free"
+                }
+            }
+        },
+        "services": [
+            "mx",
+            "openvpn"
+        ]
+    }
+   }
+
+ 
+  **Form parameters**:
+        * ``domain`` *(required)* - domain to obtain the info for.
 
 .. _cmd_prov_del:
 
diff --git a/pkg/requirements-dev.pip b/pkg/requirements-dev.pip
index 55ab261..59fbd69 100644
--- a/pkg/requirements-dev.pip
+++ b/pkg/requirements-dev.pip
@@ -1,3 +1,5 @@
 ipython
 ptpython
 ipdb
+sphinx
+sphinx_rtd_theme
-- 
cgit v1.2.3