Added REST API auth documentation

intelsdi-x · Mar 4, 2016 · 5b48baa · 5b48baa
1 parent 8b6ea9b
commit 5b48baa
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 22 deletions.
diff --git a/docs/REST_API.md b/docs/REST_API.md
@@ -11,19 +11,44 @@ snap exposes a list of RESTful APIs to perform various actions. All of snap's AP
 | version | API meta version |
 
 ## API Index
-1. [Plugin API](#plugin-api)  
+1. [Authentication](#authentication)
+2. [Plugin API](#plugin-api)  
  * [Plugin Response Parameters](#plugin-response-parameters)
  * [Plugin APIs and Examples](#plugin-apis-and-examples)
-2. [Metric API](#metric-api)  
+3. [Metric API](#metric-api)  
  * [Metric Response Parameters](#metric-response-parameters)  
  * [Metric APIs and Examples](#metric-apis-and-examples)
-3. [Task API](#task-api)  
+4. [Task API](#task-api)  
  * [Task API Response Parameters](#task-api-response-parameters)  
  * [Task APIs and Examples](#task-apis-and-examples)
-4. [Tribe API](#tribe-api)  
+5. [Tribe API](#tribe-api)  
  * [Tribe API Response Parameters](#tribe-api-response-parameters)  
  * [Tribe APIs and Examples](#tribe-apis-and-examples)
 
+### Authentication
+Enabled in snapd
+```
+curl -L http://localhost:8181/v1/plugins
+```
+```
+Not Authorized
+```
+```
+curl -L http://localhost:8181/v1/plugins -u snap
+Enter host password for user 'snap':
+```
+```json
+{
+  "meta": {
+    "code": 200,
+    "message": "Plugin list returned",
+    "type": "plugin_list_returned",
+    "version": 1
+  },
+  "body": {}
+}
+```
+
 ## Plugin API
 Plugin RESTful APIs provide the functionality to load, unload and retrieve plugin information. You may see plugin APIs along with their request and response attributes as following:
 
@@ -57,15 +82,15 @@ _**Example Response**_
   "body": {
     "loaded_plugins": [
       {
-        "name": "mock1",
+        "name": "mock",
         "version": 1,
         "type": "collector",
         "signed": false,
         "status": "loaded",
         "loaded_timestamp": 1447977606
       },
       {
-        "name": "mock2",
+        "name": "mock",
         "version": 2,
         "type": "collector",
         "signed": false,
@@ -97,7 +122,7 @@ List plugins for the given type, name, and version
 
 _**Example Request**_
 ```
-curl -L http://localhost:8181/v1/plugins/collector/mock1/1
+curl -L http://localhost:8181/v1/plugins/collector/mock/1
 ```
 _**Example Response**_
 ```json
@@ -109,7 +134,7 @@ _**Example Response**_
     "version": 1
   },
   "body": {
-    "name": "mock1",
+    "name": "mock",
     "version": 1,
     "type": "collector",
     "signed": false,
@@ -123,21 +148,21 @@ Load a plugin
 
 _**Example Request**_
 ```
-curl -X POST -F plugin=@build/plugin/snap-collector-mock1 http://localhost:8181/v1/plugins
+curl -X POST -F plugin=@build/plugin/snap-collector-mock http://localhost:8181/v1/plugins
 ```
 _**Example Response**_
 ```json
 {
   "meta": {
     "code": 201,
-    "message": "Plugins loaded: mock1(collector v1)",
+    "message": "Plugins loaded: mock(collector v1)",
     "type": "plugins_loaded",
     "version": 1
   },
   "body": {
     "loaded_plugins": [
       {
-        "name": "mock1",
+        "name": "mock",
         "version": 1,
         "type": "collector",
         "signed": false,
@@ -153,19 +178,19 @@ Unload a plugin for the given type, name, and version
 
 _**Example Request**_
 ```
-curl -X DELETE http://localhost:8181/v1/plugins/collector/mock1/1   
+curl -X DELETE http://localhost:8181/v1/plugins/collector/mock/1   
 ```
 _**Example Response**_
 ```json
 {
   "meta": {
     "code": 200,
-    "message": "Plugin successfully unloaded (mock1v1)",
+    "message": "Plugin successfuly unloaded (mockv1)",
     "type": "plugin_unloaded",
     "version": 1
   },
   "body": {
-    "name": "mock1",
+    "name": "mock",
     "version": 1,
     "type": "collector"
   }
@@ -176,7 +201,7 @@ Retrieve the config for the given type, name, and version plugin
 
 _**Example Request**_
 ```
-curl -L http://localhost:8181/v1/plugins/collector/mock1/1/config  
+curl -L http://localhost:8181/v1/plugins/collector/mock/1/config  
 ```
 _**Example Response**_
 ```json

diff --git a/docs/SNAPCTL.md b/docs/SNAPCTL.md
@@ -29,6 +29,8 @@ $ $SNAP_PATH/bin/snapctl [global options] command [command options] [arguments..
 --url, -u 'http://localhost:8181'    Sets the URL to use [$SNAP_URL]
 --insecure                           Ignore certificate errors when snap's API is running HTTPS
 --api-version, -a 'v1'               The snap API version
+--password, -p			             Password for REST API authentication
+--config, -c 			             Path to a config file [$SNAPCTL_CONFIG_PATH]
 --help, -h                           show help
 --version, -v                        print the version
 ```

diff --git a/docs/SNAPD.md b/docs/SNAPD.md
@@ -41,6 +41,7 @@ $ $SNAP_PATH/bin/snapd [global options] command [command options] [arguments...]
 --config                                     A path to a config file
 --rest-https                                 start snap's API as https
 --rest-key                                   A path to a key file to use for HTTPS deployment of snap's REST API
+--rest-auth					                 Enables snap's REST API authentication
 --tribe-node-name 'tjerniga-mac01.local'     Name of this node in tribe cluster (default: hostname) [$SNAP_TRIBE_NODE_NAME]
 --tribe                                      Enable tribe mode [$SNAP_TRIBE]
 --tribe-seed                                 IP (or hostname) and port of a node to join (e.g. 127.0.0.1:6000) [$SNAP_TRIBE_SEED]
@@ -62,10 +63,10 @@ $SNAP_PATH/bin/snapd --version
 
 ### Output
 ```
-$ $SNAP_PATH/bin/snapd -l 1 -t 0
+$ $SNAP_PATH/bin/snapd -l 1 -t 0 --rest-auth 
 ```
 ```
-INFO[0000] Starting snapd (version: v0.9.0-beta)
+INFO[0000] Starting snapd (version: unknown)
 INFO[0000] setting GOMAXPROCS to: 1 core(s)
 INFO[0000] control started                               _block=start _module=control
 INFO[0000] module started                                _module=snapd block=main snap-module=control
@@ -74,12 +75,15 @@ INFO[0000] module started                                _module=snapd block=mai
 INFO[0000] setting plugin trust level to: disabled
 INFO[0000] auto discover path is disabled
 INFO[0000] Configuring REST API with HTTPS set to: false  _module=_mgmt-rest
-INFO[0000] Starting REST API on :8181                    _module=_mgmt-rest
-INFO[0000] Rest API is enabled
-INFO[0000] snapd started                                 _module=snapd block=main
-INFO[0000] setting log level to: debug
+INFO[0000] REST API authentication is enabled
+What password do you want to use for authentication?
+Password:
+INFO[0111] REST API authentication password is set
+INFO[0111] Starting REST API on :8181                    _module=_mgmt-rest
+INFO[0111] REST API is enabled
+INFO[0111] snapd started                                 _module=snapd block=main
+INFO[0111] setting log level to: debug
 ```
-
 ## More information
 * [REST_API.md](REST_API.md)
 * [PLUGIN_SIGNING.md](PLUGIN_SIGNING.md)