API: Modules

From Yombo
Jump to: navigation, search

Summary

Manages modules through the Yombo API. This allows creating, updating, and deleting personal modules. Any modules promoted to public access cannot be managed by the user. Please contact Yombo support to make any changes.

GET - All module

Retrieve all modules available to the current user. This includes public modules and private modules specific to the user.

Filters

List of available filters:

  • id
  • label
  • machine_label
  • description
  • public
  • status
  • created_at
  • updated_at

Request URLs

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

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/module?_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/module?_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/module?_pagelimit=1",
 4         "uri_description": "List of modules, includes private modules for logged in users.",
 5         "doc_uri": "https://yombo.net/API:Modules",
 6         "module": [
 7             {
 8                 "id": "3M2VK9x7q9r",
 9                 "module_type": "interface",
10                 "machine_label": "InsteonPLM",
11                 "label": "Insteon PLM",
12                 "short_description": "A Yombo Module that adds support for sending Insteon commands to the power lines through a USB or serial port. An Insteon API module is required.",
13                 "medium_description": "A Yombo Module that adds support for sending Insteon commands to the power lines through a USB or serial port. An Insteon API module is required.\r\n\r\n* asdf\r\n* zxcv",
14                 "description": "= Summary =\r\nA Yombo module that adds support for sending Insteon commands to the power lines through a USB or serial port. An Insteon API module is required.\r\n\r\n= Usage=\r\nThis module is an interface module between the Insteon API module and an Insteon PLM. The Insteon API module is required before this module can be used.\r\n\r\n= Installation = \r\nFrom the Gateway web interface (or other application), simply mark this module as being used by the gateway, and the gateway will download and install this module automatically.\r\n\r\n= Requirements =\r\nAn Insteon interface module is required to send commands to Insteon devices.\r\n\r\n= License =\r\n\r\nSee LICENSE.md in reposiorty for full details.\r\n\r\nThis module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\r\n\r\nThe GNU General Public License can be found here: [http://www.gnu.org/licenses GNU.Org]\r\n\r\nThe [https://yombo.net Yombo] team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.",
15                 "medium_description_html": "<p>A Yombo Module that adds support for sending Insteon commands to the power lines through a USB or serial port. An Insteon API module is required.</p>\n<ul><li>asdf</li>\n<li>zxcv</li>\n</ul>",
16                 "description_html": "<h1>Summary</h1>\n<p>A Yombo module that adds support for sending Insteon commands to the power lines through a USB or serial port. An Insteon API module is required.</p>\n<h1>Usage</h1>\n<p>This module is an interface module between the Insteon API module and an Insteon PLM. The Insteon API module is required before this module can be used.</p>\n<h1>Installation</h1>\n<p>From the Gateway web interface (or other application), simply mark this module as being used by the gateway, and the gateway will download and install this module automatically.</p>\n<h1>Requirements</h1>\n<p>An Insteon interface module is required to send commands to Insteon devices.</p>\n<h1>License</h1>\n<p>See LICENSE.md in reposiorty for full details.</p>\n<p>This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.</p>\n<p>The GNU General Public License can be found here: <a class=\"external text\" href=\"http://www.gnu.org/licenses\">GNU.Org</a></p>\n<p>The <a class=\"external text\" href=\"https://yombo.net\">Yombo</a> team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</p>",
17                 "see_also": null,
18                 "repository_link": "https://github.com/yombo/module-insteonplm",
19                 "issue_tracker_link": "https://github.com/yombo/module-insteonplm/issues",
20                 "install_count": 0,
21                 "doc_link": "https://yombo.net/modules/insteonplm",
22                 "git_link": "https://github.com/yombo/module-insteonplm.git",
23                 "prod_branch": "master",
24                 "dev_branch": "",
25                 "prod_version": "278d0504f4d7a1b59bc1",
26                 "dev_version": null,
27                 "prod_updated": 1515439589,
28                 "dev_updated": null,
29                 "public": 2,
30                 "status": 1,
31                 "created_at": 1482065387,
32                 "updated_at": 1515440180,
33                 "variable_groups": [
34                     {
35                         "id": "vMqyoGVp3jRPe",
36                         "relation_id": "3M2VK9x7q9r",
37                         "relation_type": "module",
38                         "group_machine_label": "connections",
39                         "group_label": "Interface Connection",
40                         "group_description": "Interface connection information for serial/usb port.",
41                         "group_weight": 1,
42                         "status": 1,
43                         "created_at": 1482065388,
44                         "updated_at": 1482065388
45                     }
46                 ],
47                 "variable_fields": [
48                     {
49                         "id": "5rWlbLybg2yXn3",
50                         "group_id": "vMqyoGVp3jRPe",
51                         "field_machine_label": "port",
52                         "field_label": "Port Name",
53                         "field_description": "Port name to find device. either /dev/ttyUSB0, com1:, /dev/custom_map_name",
54                         "field_weight": 0,
55                         "value_required": 0,
56                         "value_max": 0,
57                         "value_min": 0,
58                         "encryption": "nosuggestion",
59                         "value_casing": "none",
60                         "input_type_id": "gowWdDyk",
61                         "default_value": "",
62                         "field_help_text": "For linux machines, it's advisable to setup a udev mapping for consistency. See: https://yombo.com/ for more information.",
63                         "multiple": false,
64                         "created_at": 1482065388,
65                         "updated_at": 1482065388
66                     }
67                 ],
68                 "device_types": []
69             }
70         ],
71         "locator": "module",
72         "locator_type": "objects"
73     },
74     "code": 200,
75     "warnings": [],
76     "pages": {
77         "total_items": 21,
78         "page_limit": 1,
79         "total_pages": 21,
80         "page_start": 1
81     },
82     "message": "OK",
83     "html_message": "OK"
84 }

GET - Specific module

Retrieve a specific modules id.

Request URLs

  • GET https://api.yombo.net/api/v1/module/{module_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..." \
https://api.yombo.net/api/v1/module/MXOBjzXKzkN
  <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/module/MXOBjzXKzkN
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/module/MXOBjzXKzkN",
 4         "uri_description": "Detailed information for a single module.",
 5         "doc_uri": "https://yombo.net/API:Modules",
 6         "module": {
 7             "id": "MXOBjzXKzkN",
 8             "module_type": "logic",
 9             "machine_label": "GarageDoor",
10             "label": "Garage Door",
11             "short_description": "This Yombo module makes 'dumb' garages into smart ones by adding logic to control a garage door (or devices that act like garage doors).",
12             "medium_description": "This Yombo module makes 'dumb' garages into smart ones by adding logic to control a garage door (or devices that act like garage doors). This module extends the capabilities of the [https://yombo.net Yombo Gateway] by adding logic to control garage door (or devices that act like garage doors).\r\n",
13             "description": "= Summary =\r\n\r\nThis Yombo module makes 'dumb' garages into smart ones by adding logic to control\r\na garage door (or devices that act like garage doors).\r\n\r\n== Usage ==\r\n\r\nThis module extends the capabilities of the [https://yombo.net Yombo Gateway]\r\nby adding logic to control garage door (or devices that act like garage doors).\r\n\r\n== Garage Door ==\r\n\r\n* ''Warning''\r\n** Caution should be used when operating garage doors remotely. Video cameras or other sensors should be used to validate the safety of operation.\r\n\r\nTo act like a garage door, 2 devices are required:\r\n\r\n# An input sensor to determine if the garage door is 'closed' (or low, 0, off).\r\n# A control device connected to a relay or some output controller.\r\n\r\nOptional: An \"all clear\" device can be used to note if it's safe to operate the garage door. This device can be any real or virtual device or state. If the device or state has one of the following values, this module will accept and process commands: on, 1, high, ok\r\n\r\nThis module uses the 'control' device and pulses the relay to simulate someone pushing a garage door opener button.\r\n\r\n== Installation ==\r\n\r\nSimply mark this module as being used by the gateway, and the gateway will download and install this module automatically.\r\n\r\n== Requirements ==\r\n\r\nSee \"Garage Door\" above for requirements.\r\n\r\n== License ==\r\n\r\nThe [https://yombo.net Yombo] team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\r\n\r\nSee LICENSE file for full details.\r\n",
14             "medium_description_html": "<p>This Yombo module makes 'dumb' garages into smart ones by adding logic to control a garage door (or devices that act like garage doors). This module extends the capabilities of the <a class=\"external text\" href=\"https://yombo.net\">Yombo Gateway</a> by adding logic to control garage door (or devices that act like garage doors).</p>",
15             "description_html": "<h1>Summary</h1>\n<p>This Yombo module makes 'dumb' garages into smart ones by adding logic to control a garage door (or devices that act like garage doors).</p>\n<h2>Usage</h2>\n<p>This module extends the capabilities of the <a class=\"external text\" href=\"https://yombo.net\">Yombo Gateway</a> by adding logic to control garage door (or devices that act like garage doors).</p>\n<h2>Garage Door</h2>\n<ul><li><i>Warning</i>\n<ul><li>Caution should be used when operating garage doors remotely. Video cameras or other sensors should be used to validate the safety of operation.</li>\n</ul></li>\n</ul><p>To act like a garage door, 2 devices are required:</p>\n<ol><li>An input sensor to determine if the garage door is 'closed' (or low, 0, off).</li>\n<li>A control device connected to a relay or some output controller.</li>\n</ol><p>Optional: An \"all clear\" device can be used to note if it's safe to operate the garage door. This device can be any real or virtual device or state. If the device or state has one of the following values, this module will accept and process commands: on, 1, high, ok</p>\n<p>This module uses the 'control' device and pulses the relay to simulate someone pushing a garage door opener button.</p>\n<h2>Installation</h2>\n<p>Simply mark this module as being used by the gateway, and the gateway will download and install this module automatically.</p>\n<h2>Requirements</h2>\n<p>See \"Garage Door\" above for requirements.</p>\n<h2>License</h2>\n<p>The <a class=\"external text\" href=\"https://yombo.net\">Yombo</a> team and other contributors hopes that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</p>\n<p>See LICENSE file for full details.</p>",
16             "see_also": null,
17             "repository_link": "https://github.com/yombo/module-garagedoor",
18             "issue_tracker_link": "https://github.com/yombo/module-garagedoor/issues",
19             "install_count": 0,
20             "doc_link": "https://yombo.net/modules/garagedoor",
21             "git_link": "https://github.com/yombo/module-garagedoor.git",
22             "prod_branch": "master",
23             "dev_branch": "develop",
24             "prod_version": "3228bfe9016df27789d4",
25             "dev_version": null,
26             "prod_updated": 1515442807,
27             "dev_updated": null,
28             "public": 2,
29             "status": 1,
30             "created_at": 1482065387,
31             "updated_at": 1515443301,
32             "variable_groups": [],
33             "variable_fields": [],
34             "device_types": [
35                 {
36                     "id": "7LwoVGYvXK5Jv3P1",
37                     "module_id": "MXOBjzXKzkN",
38                     "device_type_id": "o6xaZXbQ",
39                     "created_at": 1494579295
40                 }
41             ]
42         },
43         "locator": "module",
44         "locator_type": "object"
45     },
46     "code": 200,
47     "warnings": [],
48     "message": "OK",
49     "html_message": "OK"
50 }

POST - Create new module

Creates a new module. Rules for public and status fields apply.

Request URLs

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

Parameters

Name Type Description
Required
machine_name string Machine name for this comand. Once set, this cannot be changed. Can only contain: a-z and _ (underscore).
label string A short human friendly label for the module.
description string A detailed description of what the module does.
Optional
voice_cmd string Used by various systems to compile a possible list of voice commands for devices. This is what the person would say or type to activate the command. Usually the same as the label or machine_label.
status integer Default: 1 - Status for the command.
public integer Default: 0 - If the command should be public.

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 '{"label": "A magical module", "machine_label": "magical_module",
"short_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
"medium_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
"description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe '''required'''.",
"public": "1", "module_type": "logic", "git_link:https": "//github.com/yombo/module-magic.git",
"doc_link:https": "//yombo.net/modules", "prod_branch": "master", "dev_branch": "develop",
"repository_link": "https://github.com/yombo/module-magic"}' \
https://api.yombo.net/api/v1/module
  <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/module'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "machine_name": "disabler",
    "label": "Disabler",
    "description": "Disables something. This is a test module for demonstration.",
    }

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/module",
 4         "uri_description": "Create new module.",
 5         "doc_uri": "https://yombo.net/API:Modules",
 6         "module": {
 7             "id": "zwaKXy9KrR9",
 8             "module_type": "logic",
 9             "machine_label": "magical_module",
10             "label": "A magical module",
11             "short_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
12             "medium_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
13             "description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe '''required'''.",
14             "medium_description_html": "<p>This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.</p>",
15             "description_html": "<p>This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe <b>required</b>.</p>",
16             "see_also": null,
17             "repository_link": "https://github.com/yombo/module-magic",
18             "issue_tracker_link": "",
19             "install_count": 0,
20             "doc_link": "https://yombo.net/modules",
21             "git_link": "https://github.com/yombo/module-magic.git",
22             "prod_branch": "master",
23             "dev_branch": "develop",
24             "prod_version": null,
25             "dev_version": null,
26             "prod_updated": null,
27             "dev_updated": null,
28             "public": 1,
29             "status": 1,
30             "created_at": 1518729117,
31             "updated_at": 1518729117
32         },
33         "locator": "module",
34         "locator_type": "object"
35     },
36     "code": 201,
37     "warnings": [],
38     "message": "Created",
39     "html_message": "Created"
40 }

PUT / PATCH - Update a module

Update a module. 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/module/{module_id}
  • PUT https://api.yombo.net/api/v1/module/{module_id}

Parameters

See post new module 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 PUT -d '{"public": 1}' \
https://api.yombo.net/api/v1/module/zwaKXy9KrR9
  <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/module/zwaKXy9KrR9'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "piblic": 1,
    }

response = requests.put(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/module/zwaKXy9KrR9",
 4         "uri_description": "Update (patch) module.",
 5         "doc_uri": "https://yombo.net/API:Modules",
 6         "module": {
 7             "id": "zwaKXy9KrR9",
 8             "module_type": "logic",
 9             "machine_label": "magical_module",
10             "label": "A magical module",
11             "short_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
12             "medium_description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.",
13             "description": "This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe '''required'''.",
14             "medium_description_html": "<p>This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe required.</p>",
15             "description_html": "<p>This module provides support for magic wands, magic hats, magic boxes, specialy bunnies, and extra long scarfs. Magic school training maybe <b>required</b>.</p>",
16             "see_also": null,
17             "repository_link": "https://github.com/yombo/module-magic",
18             "issue_tracker_link": "",
19             "install_count": 0,
20             "doc_link": "https://yombo.net/modules",
21             "git_link": "https://github.com/yombo/module-magic.git",
22             "prod_branch": "master",
23             "dev_branch": "develop",
24             "prod_version": null,
25             "dev_version": null,
26             "prod_updated": null,
27             "dev_updated": null,
28             "public": "1",
29             "status": 1,
30             "created_at": 1518729117,
31             "updated_at": 1518729117
32         },
33         "locator": "module",
34         "locator_type": "object"
35     },
36     "code": 200,
37     "warnings": [],
38     "message": "Updated",
39     "html_message": "Updated"
40 }

DELETE - Delete a module

Delete a module. This doesn't actually delete the module right away, but simply marks it for deletion later. This is the same as setting the status to 2. To undelete the module, simply change the status back to 1.

Request URLs

  • DELETE https://api.yombo.net/api/v1/module/{module_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/module/zwaKXy9KrR9
  <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/module/zwaKXy9KrR9'
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/module/zwaKXy9KrR9",
 4         "uri_description": "Module deleted",
 5         "doc_uri": "https://yombo.net/API:Modules",
 6         "module": "Deleted",
 7         "locator": "module",
 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.