Differences

This shows you the differences between two versions of the page.

Link to this comparison view

indigo_2022.2_documentation:api [2024/06/27 00:08] – external edit 127.0.0.1indigo_2022.2_documentation:api [2025/04/14 20:10] (current) – external edit 127.0.0.1
Line 3: Line 3:
 In Indigo v2022.2, we’ve completely redesigned the Indigo Web Server plugin (commonly referred to as IWS). The first major change is the new Indigo Touch for Web UI. We know you'll love this new UI (particularly given the old UI which was super dated): In Indigo v2022.2, we’ve completely redesigned the Indigo Web Server plugin (commonly referred to as IWS). The first major change is the new Indigo Touch for Web UI. We know you'll love this new UI (particularly given the old UI which was super dated):
  
-{{:indigo_2022.2_documentation:itw_screenshot.png?500|}}+{{:indigo_2022.2_documentation:itw_screenshot.png?nolink&500|ITW Screen Shot Image}}
  
 This article, however, is about the two new APIs in IWS that developers can use to integrate Indigo with external services: This article, however, is about the two new APIs in IWS that developers can use to integrate Indigo with external services:
Line 10: Line 10:
   * [[#HTTP API]] – shares as much of the messaging construction with the WebSocket interface as is practical.   * [[#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 and API Keys (either as a query string or preferably an Authorization header) depending on how the user configures it in the Start Local Server dialog. +Both of these APIs are authenticated with HTTP Digest and API Keys (either as a query string or preferably an Authorization header) depending on how the user configures it in the Start Local Server dialog.
  
 <color red>**NOTE**:</color> <color red>**NOTE**:</color>
Line 20: Line 20:
 A quick note on versioning: moving forward, all APIs will be versioned under the following scheme: A quick note on versioning: moving forward, all APIs will be versioned under the following scheme:
  
-  * ''%%/v2/%%'' - this is the top level version number and will change as necessary+  * ''<nowiki>/v2/</nowiki>'' - this is the top level version number and will change as necessary
  
 ==== Python vs JavaScript ==== ==== Python vs JavaScript ====
Line 36: Line 36:
  
  
-Python developers will notice the use of ''%%null%%'' in the message descriptions. This corresponds to the Python ''%%None%%'' object. Also of note are the booleans ''%%true%%'' and ''%%false%%'', which are capitalized in Python but not in JSON. Here’s a handy cheat sheet:+Python developers will notice the use of ''<nowiki>null</nowiki>'' in the message descriptions. This corresponds to the Python ''<nowiki>None</nowiki>'' object. Also of note are the booleans ''<nowiki>true</nowiki>'' and ''<nowiki>false</nowiki>'', which are capitalized in Python but not in JSON. Here’s a handy cheat sheet:
  
 ^Python^JSON Equivalent^ ^Python^JSON Equivalent^
Line 89: Line 89:
 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: 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:
  
-''%%wss://YOUR-REFLECTOR-NAME.indigodomo.net/v2/api/ws/device-feed?api-key=YOUR-API-KEY%%''+''//<nowiki>wss://YOUR-REFLECTOR-NAME.indigodomo.net/v2/api/ws/device-feed?api-key=YOUR-API-KEY</nowiki>//''
  
 Note the protocol: ''**wss**''. WebSockets actually begin their life as HTTP/HTTPS connections, which the WebSocket client then requests the server to upgrade to a WebSocket. In this respect, you can think of WSS as HTTPS (protected) and WS as HTTP (unprotected). When using WSS, 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), but those connections will be WS and **will not be secure**. It is highly recommended that you always use your Indigo Reflector because it provides a very simple and **secure** solution for accessing your system. <color red>IMPORTANT! Be sure not to share your API keys with anyone not authorized to use them — especially in posts to the Indigo user forums.</color> Note the protocol: ''**wss**''. WebSockets actually begin their life as HTTP/HTTPS connections, which the WebSocket client then requests the server to upgrade to a WebSocket. In this respect, you can think of WSS as HTTPS (protected) and WS as HTTP (unprotected). When using WSS, 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), but those connections will be WS and **will not be secure**. It is highly recommended that you always use your Indigo Reflector because it provides a very simple and **secure** solution for accessing your system. <color red>IMPORTANT! Be sure not to share your API keys with anyone not authorized to use them — especially in posts to the Indigo user forums.</color>
Line 788: Line 788:
 ==== Log Feed ==== ==== 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. +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: Here are the URLs you will use to connect to this feed:
Line 1687: Line 1687:
 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#generating_a_dictionary_for_a_device |Generating a Dictionary for a device]] section of the IOM Reference for details. 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#generating_a_dictionary_for_a_device |Generating a Dictionary for a device]] section of the IOM Reference for details.
  
-<html><span style="color: #3B6C35; background: rgba(92, 142, 55, .4); border: #5C8E37 solid 1px; border-radius: 4px; display: inline-block; width: 80px; text-align: center;">HTTP</span></html> The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.+<color red>Note:</color>The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.
  
 === Device Command Messages === === Device Command Messages ===
Line 1711: Line 1711:
 **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. **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.
  
-<html><span style="color: #4F00B7; background: #bcb8e0; border: #9542FF solid 1px; border-radius: 4px; display: inline-block; width: 80px; text-align: center;">WebSocket</span></html> 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.+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** ''[[device_class#toggle|indigo.device.toggle(123456789, delay=5, duration=10)]]'' **toggle** ''[[device_class#toggle|indigo.device.toggle(123456789, delay=5, duration=10)]]''
Line 2216: Line 2216:
 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#generating_a_dictionary_for_a_variable |Generating a Dictionary for a variable]] section of the IOM Reference for details. 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#generating_a_dictionary_for_a_variable |Generating a Dictionary for a variable]] section of the IOM Reference for details.
  
-<html><span style="color: #3B6C35; background: rgba(92, 142, 55, .4); border: #5C8E37 solid 1px; border-radius: 4px; display: inline-block; width: 80px; text-align: center;">HTTP</span></html> The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.+<color red>Note:</color>The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.
  
 === Variable Command Messages === === Variable Command Messages ===
Line 2273: Line 2273:
 </code> </code>
  
-<html><span style="color: #3B6C35; background: rgba(92, 142, 55, .4); border: #5C8E37 solid 1px; border-radius: 4px; display: inline-block; width: 80px; text-align: center;">HTTP</span></html> The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.+<color red>Note:</color> The ''**folder**'' element is only available in the HTTP API. Folders are handled differently in the WebSocket API.
  
 === Action Group Command Messages === === Action Group Command Messages ===
Line 2307: Line 2307:
 </code> </code>
  
-Note that ''%%typeVal%%'' will be one of the following values:+Note that ''typeVal'' will be one of the following values:
  
 <code python> <code python>
  • /www/perceptive/wiki/data/attic/indigo_2022.2_documentation/api.1719446928.txt.gz
  • Last modified: 2024/06/27 00:08
  • by 127.0.0.1