Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| indigo_2023.1_documentation:api [2023/09/05 19:47] – external edit 127.0.0.1 | indigo_2023.1_documentation:api [2025/02/18 20:36] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== Integration APIs ====== | ||
| + | |||
| + | his article is about the two APIs in IWS that developers can use to integrate Indigo with external services: | ||
| + | |||
| + | * [[# | ||
| + | * [[#HTTP API]] – shares as much of the messaging construction with the WebSocket interface as is practical. | ||
| + | |||
| + | Both of these APIs are authenticated with HTTP Digest, API Keys, and [[https:// | ||
| + | |||
| + | <color red> | ||
| + | * **HTTP Basic authentication** has been deprecated due to its insecure nature. | ||
| + | * The old [[https:// | ||
| + | |||
| + | ==== Versioning ==== | ||
| + | |||
| + | A quick note on versioning: all APIs will be versioned under the following scheme: | ||
| + | |||
| + | * ''< | ||
| + | |||
| + | ==== Python vs JavaScript ==== | ||
| + | |||
| + | In these APIs, we’re using [[https:// | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | We expect there will be both Python and JavaScript users integrating our APIs, so we wanted to explicitly call this out. As a primarily Python organization, | ||
| + | |||
| + | |||
| + | Python developers will notice the use of '' | ||
| + | |||
| + | ^Python^JSON Equivalent^ | ||
| + | |True |true | | ||
| + | |False |false | ||
| + | |float |Number | ||
| + | |int | ||
| + | |None |null | | ||
| + | |dict |Object | ||
| + | |list |Array | ||
| + | |tuple |Array | ||
| + | |str | ||
| + | |||
| + | If you are new to JSON, you may want to use the [[https:// | ||
| + | ===== WebSocket API ===== | ||
| + | |||
| + | The Indigo WebSocket API is a persistent connection, meaning that your app/ | ||
| + | |||
| + | There are 5 WebSocket feeds that that are available in this release: | ||
| + | |||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | |||
| + | Each feed (except log feed) sends the following server messages: | ||
| + | |||
| + | * **add** (when a new Indigo object is added) | ||
| + | * **patch** (when an Indigo object changes - you would apply the patch to an existing object) | ||
| + | * **delete** (when the Indigo object is deleted) | ||
| + | * **refresh** (when you request a fresh copy of a device or the entire list of devices) | ||
| + | |||
| + | === WebSocket Lifecycle === | ||
| + | |||
| + | The flow of how you will interact with any of the WebSockets above will generally be: | ||
| + | |||
| + | - Setup: | ||
| + | * Open the websocket connection, and | ||
| + | * Send a refresh message to obtain all of the existing instances of that Indigo type in your database. | ||
| + | - Routine operation (asynchronously processing for the lifetime of your app/ | ||
| + | * Read incoming messages from the server (add/ | ||
| + | * Write messages to the server to instruct the server to do something (commands like statusRequest, | ||
| + | - Close the connection when your app/ | ||
| + | |||
| + | The **log-feed** is different in that it will only send **add** messages with the appropriate log event object defined below. | ||
| + | |||
| + | ==== Authentication ==== | ||
| + | |||
| + | WebSocket API requests must be authenticated using an **API Key**. You can manage API Keys in the [[https:// | ||
| + | |||
| + | The best way to use an API Key is to include it in an **Authorization** header on your HTTP request. If you are using a system which does not allow you to set headers for your HTTP request, you can include the API Key as a query argument with the URL: | ||
| + | |||
| + | ''//< | ||
| + | |||
| + | Note the protocol: '' | ||
| + | |||
| + | ==== Examples ==== | ||
| + | |||
| + | The WebSocket and HTTP APIs are designed to be familiar to those that have been using the legacy RESTful API. However, anyone with knowledge of Python, JavaScript or similar languages should be able to pick up the structure of the new APIs very quickly. To help those making the transition as well as those learning to use API calls for the first time, we've laid out several examples to show how API calls are made, as well as all the current API hooks available. | ||
| + | |||
| + | Here's a simple Python script to open the device-feed and print out any messages it receives (you' | ||
| + | |||
| + | === Python Receiver Example === | ||
| + | |||
| + | This example opens a websocket connection and prints all messages received to the console. It runs until you stop it. | ||
| + | <code python> | ||
| + | import asyncio | ||
| + | import websockets | ||
| + | import json | ||
| + | |||
| + | API_KEY = ' | ||
| + | |||
| + | async def receiver(): | ||
| + | try: | ||
| + | headers = {" | ||
| + | async with websockets.connect(" | ||
| + | while True: | ||
| + | message = await websocket.recv() | ||
| + | print(json.dumps(json.loads(message), | ||
| + | except Exception as exc: | ||
| + | print(f" | ||
| + | |||
| + | asyncio.run(receiver()) | ||
| + | </ | ||
| + | |||
| + | === Python Receiver/ | ||
| + | |||
| + | This example opens a websocket connection and shows how messages can be received and sent from the same websocket connection. It runs until the loop counters run out. | ||
| + | |||
| + | <code python> | ||
| + | import asyncio | ||
| + | import json | ||
| + | from websockets import connect | ||
| + | |||
| + | API_KEY = ' | ||
| + | DEVICE_ID = 12345678 | ||
| + | HEADERS = {" | ||
| + | URI = " | ||
| + | |||
| + | async def receiver(ws): | ||
| + | try: | ||
| + | print(" | ||
| + | # Ask for a refresh of device with ID 12345678 | ||
| + | refresh_message = { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | await ws.send(json.dumps(refresh_message)) | ||
| + | counter = 0 | ||
| + | device = {} | ||
| + | |||
| + | while counter < 20: | ||
| + | # just keep looping waiting for a message to come | ||
| + | log_string = " | ||
| + | message_json = await ws.recv() | ||
| + | message = json.loads(message_json) | ||
| + | message_type = message[' | ||
| + | |||
| + | if message_type == " | ||
| + | # This is the response to the refresh message we sent above. It gets us a full copy of the device. | ||
| + | device = message[" | ||
| + | log_string = f" | ||
| + | |||
| + | elif message_type == " | ||
| + | # There' | ||
| + | if message[" | ||
| + | log_string = f"' | ||
| + | |||
| + | print(f" | ||
| + | print(f" | ||
| + | counter += 1 | ||
| + | |||
| + | except Exception as exc: | ||
| + | print(f" | ||
| + | |||
| + | async def sender(ws, count): | ||
| + | try: | ||
| + | print(" | ||
| + | message = { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | |||
| + | for count in range(10): | ||
| + | print(f" | ||
| + | msg = json.dumps(message) | ||
| + | print(f" | ||
| + | await ws.send(json.dumps(msg)) | ||
| + | await asyncio.sleep(5) | ||
| + | |||
| + | except Exception as exc: | ||
| + | print(f" | ||
| + | |||
| + | async def main(): | ||
| + | try: | ||
| + | async with connect(URI, | ||
| + | await asyncio.gather(receiver(websocket), | ||
| + | |||
| + | except Exception as exc: | ||
| + | print(f" | ||
| + | |||
| + | asyncio.run(main()) | ||
| + | </ | ||
| + | |||
| + | === JavaScript Example === | ||
| + | |||
| + | Here's a simple nodejs JavaScript to open the device-feed and print out any messages it receives (you' | ||
| + | |||
| + | <code javascript> | ||
| + | const APIKEY = " | ||
| + | |||
| + | const W3CWebSocket = require(" | ||
| + | |||
| + | console.log(" | ||
| + | |||
| + | const client = new W3CWebSocket( | ||
| + | `ws:// | ||
| + | ); | ||
| + | client.onmessage = function (message) { | ||
| + | console.log(message.data); | ||
| + | }; | ||
| + | client.onerror = function (err) { | ||
| + | console.log(`Error: | ||
| + | }; | ||
| + | </ | ||
| + | |||
| + | ==== Device Feed ==== | ||
| + | |||
| + | This is the WebSocket you'll use for all device-related communication. You will receive the following messages from the Indigo server during the lifetime of the WebSocket. | ||
| + | |||
| + | Here are the URLs you will use to connect to this feed. | ||
| + | |||
| + | ''< | ||
| + | |||
| + | ''< | ||
| + | |||
| + | === Device messages from the server === | ||
| + | |||
| + | The following are examples of all the device messages that you will receive from the server. | ||
| + | |||
| + | == add device message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | objectDict": | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | When a new device is added to the Indigo Server after you've opened the connection, you will receive this message. It contains a [[# | ||
| + | |||
| + | == update device message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [100, 0] | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [" | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [100, 0] | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [" | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [" | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [" | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [true, false] | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [100, 0] | ||
| + | ], | ||
| + | [ | ||
| + | " | ||
| + | " | ||
| + | [true, false] | ||
| + | ] | ||
| + | ] | ||
| + | }</ | ||
| + | |||
| + | Patch objects are created via the [[https:// | ||
| + | |||
| + | == device refresh messages == | ||
| + | |||
| + | When you send a command that asks to refresh the entire list of devices, you'll receive the following message from the server: | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | And if you requested just a single device refresh, you will receive the following message from the server: | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | Note that the first message includes a list of objectDict elements, and the second includes a single objectDict element. | ||
| + | |||
| + | == delete device message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | This is the simplest of the messages, as it just contains the Indigo ID of the device to delete from your collection. You'll receive this message when a device is deleted from the Indigo server and when a device' | ||
| + | |||
| + | === Device messages to the server === | ||
| + | |||
| + | You have a variety of messages you can send to the server. | ||
| + | |||
| + | == device refresh requests == | ||
| + | |||
| + | To refresh either the full device list or a single device from the server, send the following message. | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | // Specify the object type | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | If you want the entire device list, simply omit the '' | ||
| + | |||
| + | == device command messages == | ||
| + | |||
| + | To command devices to do something, you will be using the [[#Device Command Messages]] described below. For instance, to toggle a lamp device, you would send the following message: | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | You will receive a " | ||
| + | |||
| + | ==== Variable Feed ==== | ||
| + | |||
| + | This is the WebSocket you'll use for all variable-related communication. You will receive the following messages from the Indigo server during the lifetime of the WebSocket. | ||
| + | |||
| + | Here are the URLs you will use to connect to this feed. | ||
| + | |||
| + | ''< | ||
| + | |||
| + | ''< | ||
| + | |||
| + | === Variable messages from the server === | ||
| + | |||
| + | The following is an example of the variable message that you will receive from the server. | ||
| + | |||
| + | == Example variable object (dictionary in Python) == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Here are some examples of the server messages that clients will receive on the variable feed. | ||
| + | |||
| + | == add variable message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | When a new variable is added to the Indigo Server after you've opened the connection, you will receive this message. It contains a [[# | ||
| + | |||
| + | == update variable message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Variable patch objects are created via the [[https:// | ||
| + | |||
| + | == delete variable message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | This is the simplest of the messages, as it just contains the Indigo ID of the variable to delete from your collection. You'll receive this message when a variable is deleted from the Indigo server and when a variable' | ||
| + | |||
| + | === Variable messages to the server === | ||
| + | |||
| + | There are a few messages you can send to the server. | ||
| + | |||
| + | == variable refresh messages == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | == Example refresh all variables message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | === variable command messages === | ||
| + | |||
| + | The '' | ||
| + | |||
| + | == updateValue == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | // Note, values passed in the parameter dictionary must be strings. You can | ||
| + | // pass in an empty string ("" | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== Action Group Feed ==== | ||
| + | |||
| + | This is the WebSocket you'll use for all action group-related communication. You will receive the following messages from the Indigo server during the lifetime of the WebSocket. | ||
| + | |||
| + | Here are the URLs you will use to connect to this feed. | ||
| + | |||
| + | ''< | ||
| + | |||
| + | ''< | ||
| + | |||
| + | === Action Group messages from the server === | ||
| + | |||
| + | The following are examples of all the action group messages that you will receive from the server. | ||
| + | |||
| + | == Example action group object (dictionary in Python) == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Here are some examples of the server messages that clients will receive on the action feed. | ||
| + | |||
| + | == add action group message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | When a new action group is added to the Indigo Server after you've opened the connection, you will receive this message. It contains an [[# | ||
| + | |||
| + | == update action group message == | ||
| + | |||
| + | The update action group message is received when an action group has been updated on the Indigo server. It doesn' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Action group patch objects are created via the [[https:// | ||
| + | |||
| + | == delete action group message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | This is the simplest of the messages, as it just contains the Indigo ID of the action group to delete from your collection. You'll receive this message when an action group is deleted from the Indigo server and when a action group' | ||
| + | |||
| + | === Action Group messages to the server === | ||
| + | |||
| + | The following are examples of the action group messages that you can send to the server. | ||
| + | |||
| + | == action group refresh messages == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | == Example refresh all action groups message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | === action group command messages === | ||
| + | |||
| + | The '' | ||
| + | |||
| + | == Execute == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== Control Page Feed ==== | ||
| + | |||
| + | This is the WebSocket you'll use for all control page-related communication. You will receive the following messages from the Indigo server during the lifetime of the WebSocket. The control page feed has no command messages you can send to the server; rather, it's purpose is to use incoming messages to manage a list of the available control pages which (presumably) the user would select to open that page. | ||
| + | |||
| + | Here are the URLs you will use to connect to this feed. | ||
| + | |||
| + | ''< | ||
| + | |||
| + | ''< | ||
| + | |||
| + | === Control Page messages from the server === | ||
| + | |||
| + | The following are examples of the control page messages that you will receive from the server. | ||
| + | |||
| + | == Example variable object (dictionary in Python) == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Here are some examples of the server messages that clients will receive on the variable feed. | ||
| + | |||
| + | == add control page message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | When a new control page is added to the Indigo Server after you've opened the connection, you will receive this message. It contains a control page that you will want to add to your control page list (since you'll want to patch it as it changes over time - see the next section). You'll also receive this message when a control page's remote display property is changed from False to True. | ||
| + | |||
| + | == update control page message == | ||
| + | |||
| + | The update control page message is received when a control page has been updated on the Indigo server. It doesn' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Page patch objects are created via the [[https:// | ||
| + | |||
| + | == delete control page message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | This is the simplest of the messages, as it just contains the Indigo ID of the control page to delete from your collection. You'll receive this message when a control page is deleted from the Indigo server and when a control page's remote display property is set from True to False. | ||
| + | |||
| + | ==== Indigo Object Folders ==== | ||
| + | |||
| + | Each object type above may have folders. Since those folders are specific to the type, you will use the same feed (i.e. device-feed, | ||
| + | |||
| + | This is an example of a folder object. It is the same for any folder in any feed - children is the generic name for the indigo objects contained in the folder (device, variable, etc). | ||
| + | |||
| + | < | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | === refresh folder server message === | ||
| + | |||
| + | To get the full folder list from the server, send the following message. | ||
| + | |||
| + | < | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | You will then receive the following message with all of the folders for that Indigo object type. | ||
| + | |||
| + | < | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | As of this release, this is the only way to get the current state of folders (there are not add/ | ||
| + | |||
| + | ==== Log Feed ==== | ||
| + | |||
| + | Use this feed to catch all log messages as they happen in the Indigo Server. When you first open the log-feed WebSocket, you will receive the last 25 log messages from the server **//in chronological order//**. After that, the messages come through the socket as they are generated (chronological order). See the [[#Log Messages]] section below for a description of a log message object. | ||
| + | |||
| + | Here are the URLs you will use to connect to this feed: | ||
| + | |||
| + | < | ||
| + | ws:// | ||
| + | wss:// | ||
| + | </ | ||
| + | |||
| + | You won't be able to send the server any messages on the log-feed, and the only message you get will be an add message for every new log entry: | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ===== HTTP API ===== | ||
| + | |||
| + | This API is meant for use with standard HTTP as the communication mechanism. HTTP **GET** requests to get Indigo object instances in JSON format, and **POST** requests to send commands to the Indigo Server. | ||
| + | |||
| + | ==== HTTP API Endpoints ==== | ||
| + | |||
| + | The following is a summary of endpoints (URLs that you will need to use the API) that are available in this release (detail on each is further down): | ||
| + | |||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | * ''< | ||
| + | |||
| + | You’ll receive full JSON objects which represent either a list of all instances of the object type requested (for example, a list of all action groups) or an individual Indigo object instance (a single device, variable, etc.) Each individual object will be different based on the object type, class and its definition (a custom device, for example). See the [[https:// | ||
| + | |||
| + | |||
| + | ==== Authentication ==== | ||
| + | |||
| + | HTTP API requests must be authenticated using an **API Key**. You can manage API Keys in the [[https:// | ||
| + | |||
| + | The best way to use an API Key is to include it in an **Authorization** header on your HTTP request. All the examples below show this approach. If you are using a system which does not allow you to set headers for your HTTP request, you can include the API Key as a query argument with the URL: | ||
| + | |||
| + | ''< | ||
| + | |||
| + | When using HTTPS, such as when you are using your Indigo Reflector, then your API Key (in both instances) is protected by the TLS security used by the HTTPS protocol. You may use the API locally (or thorough your own router port forwarding), | ||
| + | |||
| + | ==== Getting Device Objects ==== | ||
| + | |||
| + | The HTTP API includes a couple of methods for getting device instances as JSON objects. | ||
| + | |||
| + | === Getting All Device Objects === | ||
| + | |||
| + | [[api# | ||
| + | |||
| + | ''< | ||
| + | |||
| + | Here are some examples in different languages/ | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | device_list = json.load(request) | ||
| + | print(device_list) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: `/ | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the device JSON from Indigo, parse it into an object, and log it to the console | ||
| + | http.get(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const deviceList = JSON.parse(result); | ||
| + | console.log(deviceList); | ||
| + | }) | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -H " | ||
| + | </ | ||
| + | |||
| + | === Getting a Single Device Object === | ||
| + | |||
| + | Here are a few examples in different languages that illustrate how to get device objects. | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | DEVICEID = 123456789 | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | device_instance = json.load(request) | ||
| + | print(device_instance) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const DEVICEID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: `/ | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the device JSON from Indigo, parse it into an object, and log it to the console | ||
| + | http.get(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const deviceInstance = JSON.parse(result); | ||
| + | console.log(deviceInstance); | ||
| + | }) | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -H " | ||
| + | </ | ||
| + | |||
| + | === Controlling an Indigo Device === | ||
| + | |||
| + | You can control Indigo devices by sending commands through the API that instruct Indigo how to control the device. Indigo devices come in a variety of types, and each type has its own command set. See the [[# | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | DEVICEID = 123456789 | ||
| + | |||
| + | # The message to send to the Indigo Server | ||
| + | message = json.dumps({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }).encode(" | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | reply = json.load(request) | ||
| + | print(reply) | ||
| + | </ | ||
| + | |||
| + | == JavaScript toggle from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const DEVICEID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // The message to send to the Indigo Server | ||
| + | const message = JSON.stringify({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }) | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: "/ | ||
| + | method: " | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the device JSON from Indigo, parse it into an object, and log it to the console | ||
| + | const req = http.request(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const deviceInstance = JSON.parse(result); | ||
| + | console.log(deviceInstance); | ||
| + | }) | ||
| + | }) | ||
| + | req.write(message) | ||
| + | req.end()</ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -X POST -H " | ||
| + | </ | ||
| + | |||
| + | Using these examples, you can now construct any command listed below for any device type. | ||
| + | |||
| + | === Controlling an Indigo Device with Parameters === | ||
| + | |||
| + | As noted above, Indigo devices come in a variety of types, and each type has its own command set. As a part of this command set, some devices require specific parameters in order for Indigo to be able to execute them (some devices accept optional parameters, and others do not require any parameters at all). See the [[# | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | DEVICEID = 123456789 | ||
| + | |||
| + | # The message to send to the Indigo Server | ||
| + | message = json.dumps({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }).encode(" | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | reply = json.load(request) | ||
| + | print(reply) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const DEVICEID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // The message to send to the Indigo Server | ||
| + | const message = JSON.stringify({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }) | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: "/ | ||
| + | method: " | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the device JSON from Indigo, parse it into an object, and log it to the console | ||
| + | const req = http.request(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const deviceInstance = JSON.parse(result); | ||
| + | console.log(deviceInstance); | ||
| + | }) | ||
| + | }) | ||
| + | req.write(message) | ||
| + | req.end()</ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -X POST -H " | ||
| + | </ | ||
| + | |||
| + | Using these examples, you can now construct any command listed below for any device type. | ||
| + | |||
| + | ==== Getting Variable Objects ==== | ||
| + | |||
| + | === Getting All Variable Objects === | ||
| + | |||
| + | [[api# | ||
| + | |||
| + | ''< | ||
| + | |||
| + | Here are some examples in different languages/ | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | variable_list = json.load(request) | ||
| + | print(variable_list) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: `/ | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the variable JSON from Indigo, parse it into an object, and log it to the console | ||
| + | http.get(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const VariableList = JSON.parse(result); | ||
| + | console.log(VariableList); | ||
| + | }) | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -H " | ||
| + | </ | ||
| + | |||
| + | === Getting a Single Variable Object === | ||
| + | |||
| + | Here are a few examples in different languages that illustrate how to get variable objects. | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | VARID = 123456789 | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | var_instance = json.load(request) | ||
| + | print(var_instance) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const VARID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: `/ | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the variable object JSON from Indigo, parse it into an object, and log it to the console | ||
| + | http.get(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const varInstance = JSON.parse(result); | ||
| + | console.log(varInstance); | ||
| + | }) | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -H " | ||
| + | </ | ||
| + | |||
| + | === Updating a Variable' | ||
| + | |||
| + | You can interact with Indigo variables by sending commands through the API that instruct Indigo what to do. There is only one type of Indigo variable, and the variable type has its own command set. See the [[# | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | VARIABLEID = 123456789 | ||
| + | |||
| + | # The message to send to the Indigo Server | ||
| + | message = json.dumps({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }).encode(" | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | reply = json.load(request) | ||
| + | print(reply) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const VARIABLEID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // The message to send to the Indigo Server | ||
| + | const message = JSON.stringify({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }) | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: "/ | ||
| + | method: " | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the variable JSON from Indigo, parse it into an object, and log it to the console | ||
| + | const req = http.request(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const VariableInstance = JSON.parse(result); | ||
| + | console.log(VariableInstance); | ||
| + | }) | ||
| + | }) | ||
| + | req.write(message) | ||
| + | req.end()</ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -X POST -H " | ||
| + | </ | ||
| + | |||
| + | Using these examples, you can now construct any command listed below for any variable type. | ||
| + | |||
| + | ==== Getting Action Group Objects ==== | ||
| + | |||
| + | === Getting All Action Group Objects === | ||
| + | |||
| + | [[api# | ||
| + | |||
| + | ''< | ||
| + | |||
| + | Here are some examples in different languages/ | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | action_group_list = json.load(request) | ||
| + | print(action_group_list) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: `/ | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the action group JSON from Indigo, parse it into an object, and log it to the console | ||
| + | http.get(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const actionGroupList = JSON.parse(result); | ||
| + | console.log(actionGroupList); | ||
| + | }) | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -H " | ||
| + | </ | ||
| + | |||
| + | === Executing an Action Group === | ||
| + | |||
| + | You can control Indigo action groups by sending commands through the API that instruct Indigo how to execute the action group. There is only one type of Indigo action group, and the action group type has its own command set. See the [[# | ||
| + | |||
| + | == Pure Python 3 (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code python> | ||
| + | # This is a pure python example - no additional libraries needed | ||
| + | from urllib.request import Request, urlopen | ||
| + | import json | ||
| + | |||
| + | REFLECTORNAME = " | ||
| + | APIKEY = " | ||
| + | ACTIONGROUPID = 123456789 | ||
| + | |||
| + | # The message to send to the Indigo Server | ||
| + | message = json.dumps({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }).encode(" | ||
| + | |||
| + | req = Request(f" | ||
| + | req.add_header(' | ||
| + | with urlopen(req) as request: | ||
| + | reply = json.load(request) | ||
| + | print(reply) | ||
| + | </ | ||
| + | |||
| + | == JavaScript run from nodejs (no additional libraries) == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code javascript> | ||
| + | // Things that are specific to your environment | ||
| + | const REFLECTORNAME = " | ||
| + | const APIKEY = " | ||
| + | const ACTIONGROUPID = 123456789 | ||
| + | |||
| + | // Get the http module, and tell it that you're using HTTPS | ||
| + | const http = require(" | ||
| + | |||
| + | // The message to send to the Indigo Server | ||
| + | const message = JSON.stringify({ | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }) | ||
| + | |||
| + | // These are options that you'll pass to the get call | ||
| + | const options = { | ||
| + | hostname: `${REFLECTORNAME}.indigodomo.net`, | ||
| + | path: "/ | ||
| + | method: " | ||
| + | headers: { | ||
| + | Authorization: | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | |||
| + | // Get the action group JSON from Indigo, parse it into an object, and log it to the console | ||
| + | const req = http.request(options, | ||
| + | let result = "" | ||
| + | response.on(" | ||
| + | result += chunk; | ||
| + | }) | ||
| + | response.on(" | ||
| + | const actionGroupInstance = JSON.parse(result); | ||
| + | console.log(actionGroupInstance); | ||
| + | }) | ||
| + | }) | ||
| + | req.write(message) | ||
| + | req.end()</ | ||
| + | |||
| + | == Using curl from the command line == | ||
| + | |||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | * Replace ''// | ||
| + | |||
| + | <code bash> | ||
| + | curl -X POST -H " | ||
| + | </ | ||
| + | |||
| + | Using these examples, you can now construct any command listed below for any action group type. | ||
| + | |||
| + | ===== API Messages ===== | ||
| + | |||
| + | As mentioned earlier, both the WebSocket and HTTP APIs use JSON as the message format. We have exposed JSON versions of main Indigo objects: devices, variables, action groups, and control pages. We are also exposing command messages, which parallel the IOM command namespaces (where appropriate) for each of these object types (i.e. [[device_class# | ||
| + | |||
| + | There are also two other message types: event log messages, which represent each message that flow into the Event Log window, and error messages, which is a standardized way to communicate error conditions with each API. | ||
| + | |||
| + | In this section, we will give examples of each message type and describe their use. | ||
| + | |||
| + | If you are new to JSON, you might want to use the [[https:// | ||
| + | |||
| + | ==== Device Messaging ==== | ||
| + | |||
| + | This section describes the messages that you'll use when implementing either the WebSocket or HTTP APIs. They fall into two categories: device objects and device commands. | ||
| + | |||
| + | === Device Objects === | ||
| + | |||
| + | You’ll receive full device JSON objects which represent an Indigo device instance. Each device will be slightly different based on the device class and the definition (if a custom device). See the [[object_model_reference|Indigo Object Model]] docs for device details. | ||
| + | |||
| + | == Example device object == | ||
| + | |||
| + | This is an example of an Indigo device as a JSON object. Of course, to accommodate the wide variety of supported device types, each one will be somewhat different. This one represents an Insteon Dimmer. | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Message that contain device objects generate those objects by first converting the device to a python dictionary and then converting the python dictionary to JSON. See the [[device_class# | ||
| + | |||
| + | <color red> | ||
| + | |||
| + | === Device Command Messages === | ||
| + | |||
| + | One thing you will notice as you are looking through these examples, is that they closely mirror the Python-based [[object_model_reference|IOM commands for controlling devices]]. This was intentional to make learning one API a stepping stone to another. The HTTP API messages and the WebSocket API messages are identical, and are very clearly a JSON-rendered version of the associated IOM command. | ||
| + | |||
| + | The '' | ||
| + | |||
| + | === indigo.device === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **status request** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | **Note:** This message will work on any Indigo device type, though the device that it targets may not respond to status request messages in which case it will do nothing. | ||
| + | |||
| + | This won't necessarily cause a device update message - if the device didn't have any changes after the status request, there will be no updates to the device in the server, so no update message will be sent out the websocket. | ||
| + | |||
| + | **toggle** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **turn off** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **turn on** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **lock** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **unlock** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **enable/ | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.dimmer === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **brighten** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **dim** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set brightness** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.iodevice === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **set binary output** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.sensor === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **set on state** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.speedcontrol === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **decrease speed index** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **increase speed index** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set speed index** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set speed level** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.sprinkler === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **next zone** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **pause schedule** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **previous zone** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **resume schedule** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **run schedule** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **stop schedule** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set active zone** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | === indigo.thermostat === | ||
| + | |||
| + | [[device_class# | ||
| + | |||
| + | **decrease cool setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **decrease heat setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **increase cool setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **increase heat setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set cool setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set fan mode** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set heat setpoint** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | **set hvac mode** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== Variable Messaging ==== | ||
| + | |||
| + | This section describes the messages that you'll use when implementing either the WebSocket or HTTP APIs when dealing with Indigo devices. They fall into two categories: device objects and device command messages. | ||
| + | |||
| + | === Variable Objects === | ||
| + | |||
| + | You’ll receive full variable JSON objects which represent an Indigo variable instance. See the [[object_model_reference|Indigo Object Model]] docs for device details. | ||
| + | |||
| + | == Example variable object == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Messages that contain variable objects generate those objects by first converting the variable to a python dictionary and then converting the python dictionary to JSON. See the [[variable_class# | ||
| + | |||
| + | <color red> | ||
| + | |||
| + | === Variable Command Messages === | ||
| + | |||
| + | The only action that can currently be performed on a variable is to update the value. The '' | ||
| + | |||
| + | **updateValue** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== Action Group Messaging ==== | ||
| + | |||
| + | === Action Group Objects === | ||
| + | |||
| + | You’ll receive full variable JSON objects which represent an Indigo action group instance. See the [[object_model_reference|Indigo Object Model]] docs for action group details. | ||
| + | |||
| + | == Example action group object == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | <color red> | ||
| + | |||
| + | === Action Group Command Messages === | ||
| + | |||
| + | There is only a single action group command, and that's to execute it. The '' | ||
| + | |||
| + | ** execute ** '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== Log Messages ==== | ||
| + | |||
| + | We convert the event Indigo dictionary into a python dictionary in the '' | ||
| + | |||
| + | === Example Log Message === | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Note that '' | ||
| + | |||
| + | <code python> | ||
| + | EVENT_TYPES = { | ||
| + | Application = 0, | ||
| + | Error = 1, | ||
| + | Error_Client = 2, | ||
| + | Warning = 3, | ||
| + | Warning_Client = 4, | ||
| + | Debug_Server = 5, | ||
| + | Debug_Client = 6, | ||
| + | Debug_Plugin = 7, | ||
| + | Custom = 8, | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | You can use the values above to help determine any kind of decoration you want to use when displaying or otherwise interpreting the log event. | ||
| + | |||
| + | |||
| + | ===== Error Messaging ===== | ||
| + | |||
| + | Error messages will be returned to API clients in the event that something didn’t go as planned. The structure of messages returned will depend on what went wrong and how the message was sent. **Note that folder messages are added to the feed by the server; there are no folder endpoints to manage folders from a client at this time.** | ||
| + | |||
| + | A generic example message is provided in JSON format: | ||
| + | |||
| + | == Generic Error Message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | where the value of the JSON name (or key) '' | ||
| + | |||
| + | == Example API Call == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | You will receive the following error response: | ||
| + | |||
| + | == Resulting Error Message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | The '' | ||
| + | |||
| + | - '' | ||
| + | - '' | ||
| + | - '' | ||
| + | - '' | ||
| + | |||
| + | based on the '' | ||
| + | |||
| + | '' | ||
| + | |||
| + | === Invalid JSON === | ||
| + | |||
| + | One other type of error that you may receive would be if you POST a string (or something else, like XML, etc.) that’s not JSON. This will result in the following message return: | ||
| + | |||
| + | == Example Invalid JSON Message == | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | We will return the entire request body since it isn’t valid JSON, and we don’t know what else to do with it. | ||
| + | |||
| + | === Web Server Warnings === | ||
| + | Occasionally, | ||
| + | |||
| + | //'' | ||
| + | |||
| + | The codes are standard HTTP response codes and may help you to determine what happened. The most common codes you might encounter are: | ||
| + | |||
| + | ^ Code ^ Condition | ||
| + | | 200 | OK or Success | ||
| + | | 400 | Bad Request | ||
| + | | 401 | Unauthorized | ||
| + | | 404 | Not Found |Indicates that the server cannot find the requested resource. | | ||
| + | | 500 | Internal Server Error |Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. | | ||
| + | |||
| + | You might see another code from time to time, and a complete list of codes and their meanings can be found on the [[https:// | ||