mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-18 23:06:58 +00:00
Extend and update API documentation (#4485)
This commit is contained in:
Fabian Affolter
GitHub
parent
a7a467065d
commit
1330075f56
25
source/_components/api.markdown
Normal file
25
source/_components/api.markdown
Normal file
@ -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.
|
||||
@ -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.
|
||||
|
||||
|
||||
25
source/_components/websocket_api.markdown
Normal file
25
source/_components/websocket_api.markdown
Normal file
@ -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/) .
|
||||
@ -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/).
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user