浏览代码

add rest api doc

nico 8 年之前
父节点
当前提交
ec920a6ab4
共有 2 个文件被更改,包括 170 次插入1 次删除
  1. 35 0
      Docs/settings.md
  2. 135 1
      Docs/signals.md

+ 35 - 0
Docs/settings.md

@@ -163,3 +163,38 @@ random_wake_up_sounds:
 
 >**Note: ** If you want to use a wake up sound instead of a wake up answer you must comment out the `random_wake_up_answers` section.
 E.g: `# random_wake_up_answers:`
+
+
+## Rest API
+
+A Rest API can be activated in order to:
+- List synapses
+- Get synapse's detail
+- Run a synapse
+
+For the complete API ref see the [signals documentation](signals.md)
+
+Settings examples:
+```
+rest_api:
+  active: True
+  port: 5000
+  password_protected: True
+  login: admin
+  password: secret
+```
+
+#### active
+To enable the rest api server.
+
+#### port
+The listening port of the web server. Must be an integer in range 1024-65535.
+
+#### password_protected
+If `True`, the whole api will be password protected.
+
+#### Login
+Login used by the basic HTTP authentication. Must be provided if `password_protected` is `True`
+
+#### Password
+Password used by the basic HTTP authentication. Must be provided if `password_protected` is `True`

+ 135 - 1
Docs/signals.md

@@ -98,4 +98,138 @@ Synapse "wake up" added to the crontab
 Event loaded in crontab
 ```
 
-That's it, the synapse is now scheduled and will be started automatically.
+That's it, the synapse is now scheduled and will be started automatically.
+
+## Rest API
+
+Each synapse can be started from the REST API. For configuring the API see the [settings documentation](settings.md).
+
+### Synapse API
+
+| Method | URL                      | Action               |
+|--------|--------------------------|----------------------|
+| GET    | /synapses                | List synapses        |
+| GET    | /synapses/<synapse_name> | Show synapse details |
+| POST   | /synapses/<synapse_name> | Run a synapse        |
+
+### Curl examples
+
+>**Note:** --user is only needed if `password_protected` is True
+
+#### Get all synapse
+
+Normal response codes: 200
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X GET  http://localhost:5000/synapses/
+```
+
+Output example:
+```
+{
+  "synapses": [
+    [
+      {
+        "name": "stop-kalliope",
+        "neurons": [
+          {
+            "say": {
+              "message": "Good bye"
+            }
+          },
+          "kill_switch"
+        ],
+        "signals": [
+          {
+            "order": "close"
+          }
+        ]
+      }
+    ],
+    [
+      {
+        "name": "say-hello",
+        "neurons": [
+          {
+            "say": {
+              "message": [
+                "Bonjour monsieur"
+              ]
+            }
+          }
+        ],
+        "signals": [
+          {
+            "order": "bonjour"
+          }
+        ]
+      }
+    ]
+  ]
+}
+```
+
+#### Get synapse's detail. 
+
+Normal response codes: 200
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X GET  http://localhost:5000/synapses/say-hello
+```
+
+Output example:
+```
+{
+  "synapses": {
+    "name": "say-hello",
+    "neurons": [
+      {
+        "say": {
+          "message": [
+            "Bonjour monsieur"
+          ]
+        }
+      }
+    ],
+    "signals": [
+      {
+        "order": "bonjour"
+      }
+    ]
+  }
+}
+```
+
+#### Run a synapse by its name. 
+
+Normal response codes: 201
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X POST  http://localhost:5000/synapses/say-hello
+```
+
+Output example:
+```
+{
+  "synapses": {
+    "name": "say-hello",
+    "neurons": [
+      {
+        "say": {
+          "message": [
+            "Bonjour monsieur"
+          ]
+        }
+      }
+    ],
+    "signals": [
+      {
+        "order": "bonjour"
+      }
+    ]
+  }
+}
+```