Merge ~rmescandon/snappy-hwe-snaps/+git/wifi-ap:document-api-request-from-cli into ~snappy-hwe-team/snappy-hwe-snaps/+git/wifi-ap:master

[Roberto Mier Escandon]

Added a pair of FAQs related with errors reported using REST API from cli

[Simon Fels (morphis)]

review: Needs Fixing

[Gary.Wang (gary-wzl77)]

Thanks! Just left one comment.
Also, would you mind adjusting the content position a little bit? i.e.

## Why isn't the AP automatically enabled after I've installed the snap?
...
...
...
## Can I send REST API queries from the command line?
...
...
...

If this still doesn't help, feel free to file a [bug report](report-bug.md)
...
...

review: Needs Fixing

4f91907... by Roberto Mier Escandon on 2017-09-22

added Usage section in navigation
moved rest api use from cli to a newer page
rephrased

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 6759986e9fb2592956e629d1ce1da0bf8171abfb

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/582/

[Simon Fels (morphis)]

review: Needs Fixing

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:6759986e9fb2592956e629d1ce1da0bf8171abfb
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/531/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/581
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/582
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/580/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/548/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/531/rebuild

review: Needs Fixing (continuous-integration)

71f74a3... by Roberto Mier Escandon on 2017-09-22

updated docs with more info and more addressed comments

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 4f91907db6d7c243947d257348b67ba5eb20f780

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/583/

[Gary.Wang (gary-wzl77)]

LGTM. Thanks!

review: Approve

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:4f91907db6d7c243947d257348b67ba5eb20f780
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/532/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/582
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/583
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/581/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/550/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/532/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 5bf7ab72c3d0f51ffd83822b18b34c219f6fb26f

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/585/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:5bf7ab72c3d0f51ffd83822b18b34c219f6fb26f
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/534/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/584
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/585
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/583/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/553/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/534/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 71f74a3020cf3c6cd396ac4f3dd7a11326d40abe

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/588/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:71f74a3020cf3c6cd396ac4f3dd7a11326d40abe
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/537/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/587
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/588
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/586/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/554/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/537/rebuild

review: Needs Fixing (continuous-integration)

[Simon Fels (morphis)]

review: Needs Fixing

[Jim Hodapp (jhodapp)]

Looking good, some things to fix.

review: Needs Fixing

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 71f74a3020cf3c6cd396ac4f3dd7a11326d40abe

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/589/

c67db71... by Roberto Mier Escandon on 2017-09-22

corrected english

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:71f74a3020cf3c6cd396ac4f3dd7a11326d40abe
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/538/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/588
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/589
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/587/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/555/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/538/rebuild

review: Needs Fixing (continuous-integration)

[Simon Fels (morphis)]

review: Needs Fixing

[Jim Hodapp (jhodapp)]

One more thing to fix.

review: Needs Fixing

92106f8... by Roberto Mier Escandon on 2017-09-22

final? addressing

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: c67db71684ef1171142198f1e515d1e18b2bb31d

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/591/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:c67db71684ef1171142198f1e515d1e18b2bb31d
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/539/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/589
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/591
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/589/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/557/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/539/rebuild

review: Needs Fixing (continuous-integration)

[Jim Hodapp (jhodapp)]

LGTM!

review: Approve

[Simon Fels (morphis)]

LGTM

review: Approve

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/596/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/597/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/598/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/599/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:92106f8f50d979d1cdd5ef39529c2324cff8303c
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/1/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/1/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/1/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/1/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/1/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/1/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/601/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/600/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/602/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/603/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:92106f8f50d979d1cdd5ef39529c2324cff8303c
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/3/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/3/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/3/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/3/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/3/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/3/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/625/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/626/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/624/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/627/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:92106f8f50d979d1cdd5ef39529c2324cff8303c
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/9/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/9/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/9/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/9/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/9/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/9/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/630/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/628/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/629/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 92106f8f50d979d1cdd5ef39529c2324cff8303c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/635/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:92106f8f50d979d1cdd5ef39529c2324cff8303c
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/10/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/10/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/10/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/10
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/10/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/10/rebuild

review: Needs Fixing (continuous-integration)

Unmerged commits

92106f8... by Roberto Mier Escandon on 2017-09-22

final? addressing

c67db71... by Roberto Mier Escandon on 2017-09-22

corrected english

71f74a3... by Roberto Mier Escandon on 2017-09-22

updated docs with more info and more addressed comments

4f91907... by Roberto Mier Escandon on 2017-09-22

added Usage section in navigation
moved rest api use from cli to a newer page
rephrased

6759986... by Roberto Mier Escandon on 2017-09-22

added a pair of faqs related with api rest access from cli

diff --git a/docs/faq.md b/docs/faq.md
index a2b705c..9ad08bb 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -14,6 +14,44 @@ Yes this is possible. However, there are known limitations if the device only ha
 one WiFi network device. (e.g. both need to operate on the same channel). See
 [Simultaneous STA / AP Mode](simultaneous-sta-ap-mode.md) for more details.
 
+## I am sending an HTTP post request from the command line to the wifi-ap management service but I receive a HTTP 500 error code. Why?
+
+Review your request and be sure double quotes are correctly escaped. The following 
+request will result in an error as quotes are not properly escaped:
+
+```
+$ printf "POST /v1/configuration HTTP/1.1\r\nHost: www.example.com\r\nContent-type: application/json\r\nContent-length: 20\r\n\r\n{"disabled":"false"}" | sudo nc -U /var/snap/wifi-ap/current/sockets/control
+
+
+HTTP/1.1 500 Internal Server Error
+Date: Fri, 22 Sep 2017 08:35:57 GMT
+Content-Length: 146
+Content-Type: text/plain; charset=utf-8
+
+{"result":{"kind":"internal-error","message":"Error reading the request body"},"status":"Internal Server Error","status-code":500,"type":"error"}
+```
+
+If quotes are properly escaped then the request will be accepted by the service:
+
+```
+$ printf "POST /v1/configuration HTTP/1.1\r\nHost: www.example.com\r\nContent-type: application/json\r\nContent-length: 20\r\n\r\n{\"disabled\":\"false\"}" | sudo nc -U /var/snap/wifi-ap/current/sockets/control
+
+
+HTTP/1.1 200 OK
+Date: Fri, 22 Sep 2017 08:39:05 GMT
+Content-Length: 60
+Content-Type: text/plain; charset=utf-8
+
+{"result":{},"status":"OK","status-code":200,"type":"sync"}
+```
+Also, it's recommended to put the JSON post data into a text file and redirect command input 
+from that file during your testing as it makes the post data easier to read and edit.
+``` bash
+$ sudo nc -U /var/snap/wifi-ap/current/sockets/control < _post_content_file_
+```
+
+You can find more information related to this [here](rest-api-from-command-line.md)
+
 ## Why isn't the AP automatically enabled after I've installed the snap?
 
 Normally it should automatically come up if this isn't disabled through the
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
index 4ecfe02..0cf387c 100644
--- a/docs/metadata.yaml
+++ b/docs/metadata.yaml
@@ -15,6 +15,10 @@ navigation:
         location: secure-access-point.md
       - title: Simultaneous STA / AP Mode
         location: simultaneous-sta-ap-mode.md
+  - title: Usage
+    children:
+      - title: REST API from command line
+        location: rest-api-from-command-line.md
   - title: Reference
     children:
       - title: Commands
diff --git a/docs/rest-api-from-command-line.md b/docs/rest-api-from-command-line.md
new file mode 100644
index 0000000..fb317ac
--- /dev/null
+++ b/docs/rest-api-from-command-line.md
@@ -0,0 +1,68 @@
+---
+title: "REST API From Command Line"
+table_of_contents: False
+---
+
+# REST API From Command Line
+
+The wifi-ap snap exposes a REST API for its management that can be accessed 
+through a local Unix domain socket. One of the options to make use of that 
+API is using the command line as client.
+
+You can see the details of the available API operations [here] (reference/rest-api.md)
+
+# Prerequisites
+
+You can use `nc` to send queries and print the response from the command line. `nc` is included 
+in the default set of installed packages in Ubuntu Classic and as part of the core snap when 
+you use Ubuntu Core or snaps. If not available please install via:
+
+```
+$ apt install netcat
+```
+
+# Perform REST API Operations
+
+From command line, you can query for current snap configuration by executing:
+
+```
+$ printf "GET /v1/configuration HTTP/1.1\r\n Host: www.example.com\r\n\r\n" | sudo nc -U /var/snap/wifi-ap/current/sockets/control
+```
+
+That should result in a successful response whose JSON formatted content holds a current 
+configuration of the wifi-ap service:
+```
+HTTP/1.1 200 OK
+Date: Fri, 22 Sep 2017 09:39:33 GMT
+Content-Length: 497
+Content-Type: text/plain; charset=utf-8
+
+{"result":{"debug":false,"dhcp.lease-time":"12h","dhcp.range-start":"10.0.60.3","dhcp.range-stop":"10.0.60.20","disabled":false,"share.disabled":false,"share.network-interface":"eth0","wifi.address":"10.0.60.1","wifi.channel":"6","wifi.hostapd-driver":"nl80211","wifi.interface":"wlan0","wifi.interface-mode":"direct","wifi.netmask":"255.255.255.0","wifi.operation-mode":"g","wifi.security":"open","wifi.security-passphrase":"","wifi.ssid":"Ubuntu"},"status":"OK","status-code":200,"type":"sync"}
+```
+
+The configuration can be modified by sending a POST request with the params to
+set and its new values in a JSON formatted content type body. Some HTTP headers must 
+be set in the request:
+ * *Host*: Hostname where wifi-ap snap is installed
+ * *Content-type*: Its value must be set to `application/json` 
+ * *Content-length*: Must match the exact number of characters the request body has
+
+```
+$ printf "POST /v1/configuration HTTP/1.1\r\nHost: www.example.com\r\nContent-type: application/json\r\nContent-length: 20\r\n\r\n{\"disabled\":\"false\"}" | sudo nc -U /var/snap/wifi-ap/current/sockets/control
+```
+
+A sucessful server reply means that the configuration has been updated as desired:
+
+```
+HTTP/1.1 200 OK
+Date: Fri, 22 Sep 2017 09:43:31 GMT
+Content-Length: 60
+Content-Type: text/plain; charset=utf-8
+
+{"result":{},"status":"OK","status-code":200,"type":"sync"}
+```
+
+
+!!! Note:
+    In case you need to provide body content, you have to escape the
+    double quote to not receive a malformed request error.