From b7ad2c718807bc3ede1f07696bc3c704068cdc17 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 9 May 2015 13:19:32 +0200 Subject: [PATCH 1/6] add sample curl command --- source/developers/api.markdown | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/developers/api.markdown b/source/developers/api.markdown index ac9737a5d44..b5828d9e729 100644 --- a/source/developers/api.markdown +++ b/source/developers/api.markdown @@ -18,6 +18,12 @@ In the package [`homeassistant.remote`](https://github.com/balloob/home-assistan 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`). +```bash +curl -X GET \ + -H "x-ha-access: YOUR_PASSWORD" \ + http://localhost:8123/api +``` +

You can append ?api_password=YOUR_PASSWORD to any url to log in automatically.

From 604fee3fdcb1d6871f0ea7467ac4e348a67d4f72 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 9 May 2015 13:49:37 +0200 Subject: [PATCH 2/6] add a simple python sample --- source/developers/api.markdown | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/source/developers/api.markdown b/source/developers/api.markdown index b5828d9e729..543bb06aa33 100644 --- a/source/developers/api.markdown +++ b/source/developers/api.markdown @@ -18,12 +18,28 @@ In the package [`homeassistant.remote`](https://github.com/balloob/home-assistan 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`). +There are several ways to consume the Home Assistant API. One is with `curl`: + ```bash curl -X GET \ -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api ``` +Another option is to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module. + +```python +from requests import get + +url = 'http://localhost:8123/api/' +headers = {'x-ha-access': 'YOUR_PASSWORD', + 'content-type': 'application/json'} + +response = get(url, headers=headers) + +print(response.text) +``` +

You can append ?api_password=YOUR_PASSWORD to any url to log in automatically.

@@ -251,3 +267,4 @@ It will return a message if event forwarding was cancelled successful.

If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE.

+ From ad919ed4661f2b1224cc947d69f38c012e4616b9 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 11 May 2015 11:59:18 +0200 Subject: [PATCH 3/6] rename api to rest_api --- source/developers/{api.markdown => rest_api.markdown} | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) rename source/developers/{api.markdown => rest_api.markdown} (94%) diff --git a/source/developers/api.markdown b/source/developers/rest_api.markdown similarity index 94% rename from source/developers/api.markdown rename to source/developers/rest_api.markdown index 543bb06aa33..8be90e0a52f 100644 --- a/source/developers/api.markdown +++ b/source/developers/rest_api.markdown @@ -14,11 +14,9 @@ Home Assistant runs a web server accessible on port 8123. * http://127.0.0.1:8123/ is an interface to control Home Assistant. * http://localhost:8123/api/ is a Rest API. -In the package [`homeassistant.remote`](https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the HTTP API can be found. +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). -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`). - -There are several ways to consume the Home Assistant API. One is with `curl`: +There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: ```bash curl -X GET \ @@ -36,7 +34,6 @@ headers = {'x-ha-access': 'YOUR_PASSWORD', 'content-type': 'application/json'} response = get(url, headers=headers) - print(response.text) ``` @@ -51,7 +48,9 @@ Successful calls will return status code 200 or 201. Other status codes that can - 404 (Not Found) - 405 (Method not allowed) -The api supports the following actions: +### {% linkable_title Actions %} + +The API supports the following actions: #### {% linkable_title GET /api %} Returns message if API is up and running. From acd1c7893ce4f8b1c3874e1a78362b84476c57c4 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 11 May 2015 12:06:38 +0200 Subject: [PATCH 4/6] move rest content to a separate page --- source/developers/api.markdown | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 source/developers/api.markdown diff --git a/source/developers/api.markdown b/source/developers/api.markdown new file mode 100644 index 00000000000..777ce646f2c --- /dev/null +++ b/source/developers/api.markdown @@ -0,0 +1,16 @@ +--- +layout: page +title: "Home Assistant API" +description: "Home Assistant API documentation" +date: 2015-05-11 12:00 +sidebar: false +comments: false +sharing: true +footer: true +--- + +Home Assistant is offering a RESTful API and a Python API for convenient access to +a Home Assistant instance over HTTP. + +- [Rest API](/developers/rest_api.html) +- [Python API](/developers/python_api.html) From e92b5dc6e4bcfdfe433d5b1e9f024a9f0fee4990 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 11 May 2015 12:07:06 +0200 Subject: [PATCH 5/6] move python api to a separate page --- source/developers/python_api.markdown | 31 +++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 source/developers/python_api.markdown diff --git a/source/developers/python_api.markdown b/source/developers/python_api.markdown new file mode 100644 index 00000000000..8c91fb2c021 --- /dev/null +++ b/source/developers/python_api.markdown @@ -0,0 +1,31 @@ +--- +layout: page +title: "Python API" +description: "Home Assistant Python API documentation" +date: 2015-05-11 12:00 +sidebar: false +comments: false +sharing: true +footer: true +--- + +In the package [`homeassistant.remote`](https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api.html) can be found. + +The two snippets below shows how to use the `homeassistant.remote` package: + +```python +import homeassistant.remote as remote + +api = remote.API("host", "password") +living_room = remote.get_state(api, 'group.living_room') +``` + +```python +import homeassistant.remote as remote + +api = remote.API("host", "password") +hass = remote.HomeAssistant(api) +hass.start() +living_room = hass.states.get('group.living_room') +``` + From b38069f76762c72c82c4e88b57092efa9ae95b8b Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 11 May 2015 12:16:16 +0200 Subject: [PATCH 6/6] update name --- source/_includes/custom/navigation.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 18811574933..aa1a260cc0f 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -19,9 +19,9 @@
  • Adding platform support
    • -
  • Rest API
    • +
  • API
  • Blog
  • Need help?
    • - \ No newline at end of file +