From 1330075f566482cd7ead9ca8eeb43ddcec519b2c Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sun, 21 Jan 2018 17:34:44 +0100 Subject: [PATCH] Extend and update API documentation (#4485) --- source/_components/api.markdown | 25 +++++++++++++++++++++++ source/_components/http.markdown | 4 ++-- source/_components/websocket_api.markdown | 25 +++++++++++++++++++++++ source/developers/api.markdown | 5 ++++- source/developers/python_api.markdown | 2 +- source/developers/rest_api.markdown | 2 ++ source/developers/websocket_api.markdown | 12 ++++++----- 7 files changed, 66 insertions(+), 9 deletions(-) create mode 100644 source/_components/api.markdown create mode 100644 source/_components/websocket_api.markdown diff --git a/source/_components/api.markdown b/source/_components/api.markdown new file mode 100644 index 00000000000..cdac55a1b44 --- /dev/null +++ b/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/). + +

+It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet. +

+ +```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. diff --git a/source/_components/http.markdown b/source/_components/http.markdown index 91c25d7058b..0a6d20b2cd0 100644 --- a/source/_components/http.markdown +++ b/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. diff --git a/source/_components/websocket_api.markdown b/source/_components/websocket_api.markdown new file mode 100644 index 00000000000..4eff8a8a3f6 --- /dev/null +++ b/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/). + +

+It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet. +

+ +```yaml +# Example configuration.yaml entry +websocket_api: +``` + +For details to use the WebSocket API, please refer to the [WebSocket API documentation](/developers/websocket_api/) . diff --git a/source/developers/api.markdown b/source/developers/api.markdown index b46b1fdc4d4..999647d0382 100644 --- a/source/developers/api.markdown +++ b/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/). + diff --git a/source/developers/python_api.markdown b/source/developers/python_api.markdown index 2e752f80b4c..818bb8d0771 100644 --- a/source/developers/python_api.markdown +++ b/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. diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index cf850cfbec4..bd9fc8f48c7 100644 --- a/source/developers/rest_api.markdown +++ b/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 diff --git a/source/developers/websocket_api.markdown b/source/developers/websocket_api.markdown index 3cf5796c1b3..46361af809d 100644 --- a/source/developers/websocket_api.markdown +++ b/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 - - Server sends `auth_required` message - - Client sends `auth` message + - If no further authentication necessary for the user: go to 3. + - Server sends `auth_required` 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.