Add web server and webhook matcher docs

docs/configuration-reference.md

@@ -105,6 +105,18 @@ skills:
 
 See [module options](#module-options) for installing custom skills.
 
+### `web`
+
+Configure the REST API in opsdroid.
+
+By default opsdroid will start a web server on port `8080` accessible only to localhost. For more information see the [REST API docs](rest-api).
+
+```yaml
+web:
+  host: '127.0.0.1'  # set to '0.0.0.0' to allow all traffic
+  port: 8080
+```
+
 ## Module options
 
 All modules are installed from git repositories. By default if no additional options are specified opsdroid will look for the repository at `https://github.com/opsdroid/<moduletype>-<modulename>.git`.

docs/parsers/crontab.md

@@ -6,6 +6,7 @@ The crontab parser is a bit different to other parsers. This parser doesn't take
 
 ```python
 from opsdroid.matchers import match_crontab
+from opsdroid.message import Message
 
 @match_crontab('* * * * *')
 async def mycrontabskill(opsdroid, config, message):

docs/parsers/overview.md

@@ -3,9 +3,11 @@
 When writing skills for opsdroid there are multiple parsers you can use for matching messages to your functions.
 
  * [Regular Expression](parsers/regex)
-  * `opsdroid.skills.match_regex`
+    * `opsdroid.skills.match_regex`
  * [API.AI](parsers/api.ai)
-  * `opsdroid.skills.match_apiai_action`
-  * `opsdroid.skills.match_apiai_intent`
+    * `opsdroid.skills.match_apiai_action`
+    * `opsdroid.skills.match_apiai_intent`
  * [Crontab](parsers/crontab)
-  * `opsdroid.skills.match_crontab`
+    * `opsdroid.skills.match_crontab`
+ * [Webhook](parsers/webhook)
+    * `opsdroid.skills.match_webhook`

docs/parsers/webhook.md

@@ -0,0 +1,33 @@
+# Webhook Parser
+
+Similar to the crontab parser this parser doesn't take a message as an input, it takes a webhook instead. It allows you to trigger the skill by calling a specific URL endpoint.
+
+## Example
+
+```python
+from aiohttp.web import Request
+
+from opsdroid.matchers import match_webhook
+from opsdroid.message import Message
+
+@match_webhook('examplewebhook')
+async def mycrontabskill(opsdroid, config, message):
+
+    if type(message) is not Message and type(message) is Request:
+      # Capture the request POST data and set message to a default message
+      request = await message.post()
+      message = Message("", None, connector.default_room,
+                        opsdroid.default_connector)
+
+    # Respond
+    await message.respond('Hey')
+```
+
+**Config**
+
+```yaml
+skills:
+  - name: "exampleskill"
+```
+
+The above skill would be called if you send a POST to `http://localhost:8080/skill/exampleskill/examplewebhook`. As the skill is being triggered by a webhook the `message` argument being passed in will be set to the [aiohttp Request](http://aiohttp.readthedocs.io/en/stable/web_reference.html#aiohttp.web.BaseRequest), this means you need to create an empty message to respond to. You will also need to know which connector, and possibly which room, to send the message back to. For this you can use the `opsdroid.default_connector` and `opsdroid.default_connector.default_room` properties to get some sensible defaults.

docs/rest-api.md

@@ -0,0 +1,64 @@
+# REST API
+
+There is a RESTful API for opsdroid which by default is only accessible to `localhost` on port `8080`. See the [configuration reference](configuration-reference#web) for config options.
+
+## Methods
+
+### `/` _[GET]_
+
+A test url you can use to check whether the API is running.
+
+**Example response**
+
+```json
+{
+  "timestamp": "2017-02-05T10:12:51.622981",
+  "status": 200,
+  "result": {
+    "message": "Welcome to the opsdroid API"
+  }
+}
+```
+
+### `/stats/` _[GET]_
+
+This method returns runtime statistics which could be useful in monitoring.
+
+**Example response**
+
+```json
+{
+  "timestamp": "2017-02-05T10:14:37.494541",
+  "status": 200,
+  "result": {
+    "version": "0.6.0",
+    "messages": {
+      "total_parsed": 164,
+      "webhooks_called": 28
+    },
+    "modules": {
+      "skills": 13,
+      "connectors": 1,
+      "databases": 0
+    }
+  }
+}
+```
+
+### `/skill/{skillname}/{webhookname}` _[POST]_
+
+This method family will call skills which have been decorated with the [webhook matcher](parsers/webhook). The URI format includes the name of the skill from the `configuration.yaml` and the name of the webhook set in the decorator.
+
+The response includes information on whether a skill was successfully triggered or not.
+
+**Example response**
+
+```json
+{
+  "timestamp": "2017-02-04T16:25:01.956323",
+  "status": 200,
+  "result": {
+    "called_skill": "examplewebhookskill"
+  }
+}
+```

mkdocs.yml

@@ -6,6 +6,7 @@ pages:
   - Home: 'index.md'
   - Getting Started: 'getting-started.md'
   - Configuration Reference: 'configuration-reference.md'
+  - REST API: 'rest-api.md'
   - Extending opsdroid:
     - Adding skills: 'extending/skills.md'
     - Adding connectors: 'extending/connectors.md'
@@ -14,4 +15,6 @@ pages:
     - Overview: 'parsers/overview.md'
     - Regular Expressions: 'parsers/regex.md'
     - API.AI: 'parsers/api.ai.md'
+    - Crontab: 'parsers/crontab.md'
+    - Webhook: 'parsers/webhook.md'
   - Contributing: 'contributing.md'