Extend and update API documentation (#4485)

source/_components/api.markdown

@@ -0,0 +1,25 @@
+---
+layout: page
+title: "API"
+description: "Instructions how to setup the RESTful API within Home Assistant."
+date: 2018-01-21 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: home-assistant.png
+ha_category: "Other"
+---
+
+The `api` component exposes a RESTful API and allows one to interact with a Home Assistant instance that is running headless. This component depends on the [`http` component](/components/http/).
+
+<p class='note warning'>
+It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet.
+</p>
+
+```yaml
+# Example configuration.yaml entry
+api:
+```
+
+For details to use the API, please refer to the [REST API](/developers/rest_api/) or the [Python REST API documentation](/developers/python_api/) in the "Developer" section. 

source/_components/http.markdown

@@ -65,9 +65,9 @@ http:
 
 The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/).
 
-Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/)
+Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/).
 
-On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/).
+On top of the `http` component is a [REST API](/developers/rest_api/), [Python API](/developers/python_api/) and [WebSocket API](/developers/websocket_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/).
 
 The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP. 
 

source/_components/websocket_api.markdown

@@ -0,0 +1,25 @@
+---
+layout: page
+title: "Websocket API"
+description: "Instructions how to setup the WebSocket API within Home Assistant."
+date: 2018-01-21 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: home-assistant.png
+ha_category: "Other"
+---
+
+The `websocket_api` component set up a WebSocket API and allows one to interact with a Home Assistant instance that is running headless. This component depends on the [`http` component](/components/http/).
+
+<p class='note warning'>
+It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet.
+</p>
+
+```yaml
+# Example configuration.yaml entry
+websocket_api:
+```
+
+For details to use the WebSocket API, please refer to the [WebSocket API documentation](/developers/websocket_api/) . 

source/developers/api.markdown

@@ -12,7 +12,10 @@ footer: true
 Home Assistant provides various APIs. For detail please refer to [Home Assistant API](https://dev-docs.home-assistant.io/en/dev/) documentation.
 
   * [Python API](https://dev-docs.home-assistant.io/)
-  * [Websocket API](/developers/websocket_api/)
+  * [WebSocket API](/developers/websocket_api/)
   * [REST API](/developers/rest_api/)
   * [Python REST API](/developers/python_api/)
   * [Server-sent events](/developers/server_sent_events/)
+
+If you are not using the [`frontend`](/components/frontend/) in your setup then you need to enable the components by adding them to your `configuration.yaml` file. E.g., [`websocket_api:`](/components/websocket_api/) for the WebSocket API or [`api:`](/components/api/) for the [REST API](/developers/rest_api/) and the [Python REST API](/developers/python_api/).
+

source/developers/python_api.markdown

@@ -13,7 +13,7 @@ See the [developer documentation][devdocs] for a full overview of the documentat
 
 [devdocs]: https://dev-docs.home-assistant.io/en/master/api/homeassistant.html#module-homeassistant.remote
 
-In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found.
+In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found. If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file to use the Python Remote API. 
 
 A simple way to get all current entities is to visit the "Set State" page in the "Developer Tools". For the examples below just choose one from the available entries. Here the sensor `sensor.office_temperature` and the switch `switch.livingroom_pin_2` are used.
 

source/developers/rest_api.markdown

@@ -16,6 +16,8 @@ Home Assistant runs a web server accessible on port 8123.
 
 The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)).
 
+If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file. 
+
 There are multiple ways to consume the Home Assistant Rest API. One is with `curl`:
 
 ```bash

source/developers/websocket_api.markdown

@@ -17,16 +17,18 @@ Home Assistant contains a WebSocket API. This API can be used to stream informat
 
 Connect your websocket implementation to `ws://localhost:8123/api/websocket`.
 
+If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`websocket_api` component](/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API. 
+
 ## {% linkable_title Server states %}
 
- 1. Client connects
+ 1. Client connects.
  2. Authentication phase starts
-    - If no further authentication necessary for the user: go to 3
+    - If no further authentication necessary for the user: go to 3.
-    - Server sends `auth_required` message
+    - Server sends `auth_required` message.
-    - Client sends `auth` message
+    - Client sends `auth` message.
     - If `auth` message correct: go to 3.
     - Server sends `auth_invalid`. Go to 6.
- 3. Send `auth_ok` message
+ 3. Send `auth_ok` message.
  4. Authentication phase ends.
  5. Command phase starts.
     1. Client can send commands.