API: Device command inputs

From Yombo
Jump to: navigation, search

Summary

For each command, it can accept various inputs. This allows inputs from users to be filtered and validated before being sent to a device for processing. For example, a media player might accept a media file name to play.

GET - All device command inputs

Retrieve all device types available to the current user.

Filters

List of available filters:

  • device_type_id
  • command_id
  • input_type_id
  • machine_label
  • label

Request URLs

  • GET https://api.yombo.net/api/v1/device_command_input

Parameters

None

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
https://api.yombo.net/api/v1/device_command_input?device_type_id=kJx2g8Na&input_type_id=Eb6GZr45&command_id=gaDO5dJgo397B&_pagelimit=2
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/device_command_input?device_type_id=kJx2g8Na&input_type_id=Eb6GZr45&command_id=gaDO5dJgo397B&_pagelimit=2'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }
response = requests.get(url, headers=headers)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device_command_input?_pagelimit=2&command_id=gaDO5dJgo397B&device_type_id=kJx2g8Na&input_type_id=Eb6GZr45",
 4         "uri_description": "Map of input types for given device type and commands.",
 5         "doc_uri": "https://yombo.net/API:Device_command_inputs",
 6         "device_command_input": [
 7             {
 8                 "id": "5YwKR498",
 9                 "device_type_id": "7BxzOXpb",
10                 "command_id": "6grEylY20Y1L3",
11                 "input_type_id": "YnDNnDa6",
12                 "label": "",
13                 "machine_label": "",
14                 "live_update": 0,
15                 "value_required": 1,
16                 "value_max": 0,
17                 "value_min": 0,
18                 "encryption": "nosuggestion",
19                 "value_casing": "none",
20                 "notes": null,
21                 "created_at": 1482065388,
22                 "updated_at": 1482065388,
23                 "command_label": "Send house code",
24                 "commands_machine_label": "Send house code",
25                 "input_type_label": "X10 House",
26                 "input_type_machine_label": "x10_house"
27             },
28             {
29                 "id": "Yow1BWAO",
30                 "device_type_id": "9oDQ0XVy",
31                 "command_id": "Rnpx5ZqYZbyzY",
32                 "input_type_id": "KoQpXQbV",
33                 "label": "",
34                 "machine_label": "",
35                 "live_update": 0,
36                 "value_required": 1,
37                 "value_max": 0,
38                 "value_min": 0,
39                 "encryption": "nosuggestion",
40                 "value_casing": "none",
41                 "notes": null,
42                 "created_at": 1482065388,
43                 "updated_at": 1482065388,
44                 "command_label": "Brighten",
45                 "commands_machine_label": "brighten",
46                 "input_type_label": "Insteon Address",
47                 "input_type_machine_label": "insteon_address"
48             }
49         ],
50         "locator": "device_command_input",
51         "locator_type": "objects"
52     },
53     "code": 200,
54     "warnings": [],
55     "pages": {
56         "total_items": 23,
57         "page_limit": 2,
58         "total_pages": 12,
59         "page_start": 1
60     },
61     "message": "OK",
62     "html_message": "OK"
63 }

GET - Specific device command input

Retrieve a specific device command input id. There are two ways to retrieve a single device type command:

  1. Using just the device type command id - Allows directly looking up information.
  2. Using the device type and command id - Search for the device type command.

Request URLs

  • GET https://api.yombo.net/api/v1/device_command_input/{device_command_input_id}

Parameters

None

Example

Both search methods return the same results.

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
https://api.yombo.net/api/v1/device_command_input/5YwKR498
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/device_command_input/5YwKR498
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }
response = requests.get(url, headers=headers)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device_command_input/Yow1BWAO",
 4         "uri_description": "Map of input types for given device type and commands.",
 5         "doc_uri": "https://yombo.net/API:Device_command_inputs",
 6         "device_command_input": {
 7             "id": "Yow1BWAO",
 8             "device_type_id": "9oDQ0XVy",
 9             "command_id": "Rnpx5ZqYZbyzY",
10             "input_type_id": "KoQpXQbV",
11             "label": "",
12             "machine_label": "",
13             "live_update": 0,
14             "value_required": 1,
15             "value_max": 0,
16             "value_min": 0,
17             "encryption": "nosuggestion",
18             "value_casing": "none",
19             "notes": null,
20             "created_at": 1482065388,
21             "updated_at": 1482065388,
22             "command_label": "Brighten",
23             "commands_machine_label": "brighten",
24             "input_type_label": "Insteon Address",
25             "input_type_machine_label": "insteon_address"
26         },
27         "locator": "device_command_input",
28         "locator_type": "object"
29     },
30     "code": 200,
31     "warnings": [],
32     "message": "OK",
33     "html_message": "OK"
34 }

POST - Create new device command input

Creates a new device type command mapping. You must have access modify the device type in order to complete this.

Request URLs

  • POST https://api.yombo.net/api/v1/device_command_input

Parameters

Name Type Description
Required
device_type_id string Device type to map.
command_id string Command id to map.
input_type_id string Input type to use for validation.
machine_label string An ummutable label for developers to use. A computer version of the `label`.
label string A short human friendly label for the device command input.
live_update string If any remote applications controlling a device should send the device a command while the user is still typing in input. For example, a slider to control lamp brightness. One of: 0 = No. 1 = Yes.
value_required boolean If a value is required for this input.
encryption string One of: 'nosuggestion', 'never', 'always'. Weather or not the sender should encrypt the input value using the destination gateway's public GPG key.
value_casing string One of 'none', 'upper', 'lower', 'upperfirst'. This only applies to string type inputs.
notes string Notes or description for the purpose of the device command input.
Optional
value_max integer Max length of input for a string, or max value for integers, percents, etc.
value_min integer Min length of input for a string, or min value for integers, percents, etc.

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X POST -d '{"device_type_id": "QAJqr8xZ", "command_id": "aWvzB0ENZ23JO",
"input_type_id": "b6QxNwjk", "live_update":"0", "machine_label":"robot_on_delay",
"label":"Robot on delay", "value_required:0", "encryption:":"never",
"notes":"Turns the robot on, this input allows a delay to be set in seconds to turn on.",
"value_max":"30000", "value_min":"0", "value_casing":"none"}' \
https://api.yombo.net/api/v1/device_command_input
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/device_command_input'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "device_type_id": "QAJqr8xZ",
    "command_id": "aWvzB0ENZ23JO",
    "input_type_id": "b6QxNwjk",
    "live_update":"0",
    "machine_label":"robot_on_delay",
    "label":"Robot on delay",
    "value_required:0",
    "encryption:":"never",
    "notes":"Turns the robot on, this input allows a delay to be set in seconds to turn on.",
    "value_max":"30000",
    "value_min":"0",
    "value_casing":"none"
    }

response = requests.post(url, headers=headers, json=payload)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device_command_input",
 4         "uri_description": "Map of input types for given device type and commands.",
 5         "doc_uri": "https://yombo.net/api/#dt-command-inputs",
 6         "device_command_input": {
 7             "id": "Zv7oZaWp",
 8             "device_type_id": "QAJqr8xZ",
 9             "command_id": "aWvzB0ENZ23JO",
10             "input_type_id": "b6QxNwjk",
11             "label": "Robot on delay",
12             "machine_label": "robot_on_delay",
13             "live_update": 0,
14             "value_required": 0,
15             "value_max": 30000,
16             "value_min": 0,
17             "encryption": "never",
18             "value_casing": "none",
19             "notes": "Turns the robot on, this input allows a delay to be set in seconds to turn on.",
20             "created_at": 1518576081,
21             "updated_at": 1518576081
22         },
23         "locator": "device_command_input",
24         "locator_type": "object"
25     },
26     "code": 201,
27     "warnings": [],
28     "message": "Created",
29     "html_message": "Created"
30 }

PUT / PATCH - Update a device command input

Update a device command input. When using PUT, all required parameters must be sent. When using PATCH, only send in desired changes.

Request URLs

  • PATCH https://api.yombo.net/api/v1/device_command_input/{device_type_id}
  • PUT https://api.yombo.net/api/v1/device_command_input/{device_type_id}

Parameters

See post new device type parameters.

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X PATCH -d '{"value_max": "44444"}' \
https://api.yombo.net/api/v1/device_type/QAJqr8xZ
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/device_type/QAJqr8xZ'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "value_max": "44444",
    }

response = requests.patch(url, headers=headers, json=payload)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device_command_input/Zv7oZaWp",
 4         "uri_description": "Map of input types for given device type and commands.",
 5         "doc_uri": "https://yombo.net/API:Device_command_inputs",
 6         "device_command_input": {
 7             "id": "Zv7oZaWp",
 8             "device_type_id": "QAJqr8xZ",
 9             "command_id": "aWvzB0ENZ23JO",
10             "input_type_id": "b6QxNwjk",
11             "label": "Robot on delay",
12             "machine_label": "robot_on_delay",
13             "live_update": 0,
14             "value_required": 0,
15             "value_max": "44444",
16             "value_min": 0,
17             "encryption": "never",
18             "value_casing": "none",
19             "notes": "Turns the robot on, this input allows a delay to be set in seconds to turn on.",
20             "created_at": 1518576081,
21             "updated_at": 1518577562
22         },
23         "locator": "device_command_input",
24         "locator_type": "object"
25     },
26     "code": 200,
27     "warnings": [],
28     "message": "Updated",
29     "html_message": "Updated"
30 }

DELETE - Delete a device type command

Delete a device type command mapping.

Request URLs

  • DELETE https://api.yombo.net/api/v1/device_command_input/{device_type_command_id}

Parameters

None

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X DELETE https://api.yombo.net/api/v1/device_command_input/Zv7oZaWp
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/device_command_input/Zv7oZaWp'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

response = requests.put(url, headers=headers)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device_command_input/Zv7oZaWp",
 4         "uri_description": "Delete a device command input.",
 5         "doc_uri": "https://yombo.net/API:Device_command_inputs",
 6         "device_command_input": "Deleted",
 7         "locator": "device_command_input",
 8         "locator_type": "string"
 9     },
10     "code": 200,
11     "warnings": [],
12     "message": "Deleted",
13     "html_message": "Deleted"
14 }
This page was last edited on 14 September 2018.