API: Commands

From Yombo
Jump to: navigation, search

Summary

Commands are used to control devices. Commands can be added as needed to support additional device types.

GET - All commands

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

Request URL

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

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 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
/api/v1/commands?page[size]=3

  <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/commands?page[size]=3'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results

  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">

{
    "data": [
        {
            "type": "commands",
            "id": "6a7ylqea1LsDqXb8V",
            "attributes": {
                "id": "6a7ylqea1LsDqXb8V",
                "voice_cmd": "on",
                "machine_label": "on",
                "label": "On",
                "description": "Sends an on command",
                "public": 2,
                "status": 1,
                "created_at": 1482065387,
                "updated_at": 1518130546
            },
            "links": {
                "self": "https://api.yombo.net/api/v1/commands/6a7ylqea1LsDqXb8V"
            }
        },
        {
            "type": "commands",
            "id": "pVZQKBgg5aI3BglM7",
            "attributes": {
                "id": "pVZQKBgg5aI3BglM7",
                "voice_cmd": "off",
                "machine_label": "off",
                "label": "Off",
                "description": "Sends an off command",
                "public": 2,
                "status": 1,
                "created_at": 1482065387,
                "updated_at": 1482065387
            },
            "links": {
                "self": "https://api.yombo.net/api/v1/commands/pVZQKBgg5aI3BglM7"
            }
        },
        {
            "type": "commands",
            "id": "pVZQKBg9yzTd0glM7",
            "attributes": {
                "id": "pVZQKBg9yzTd0glM7",
                "voice_cmd": "close",
                "machine_label": "close",
                "label": "Close",
                "description": "Sends a close command",
                "public": 2,
                "status": 1,
                "created_at": 1482065387,
                "updated_at": 1482065387
            },
            "links": {
                "self": "https://api.yombo.net/api/v1/commands/pVZQKBg9yzTd0glM7"
            }
        }
    ],
    "meta": {
        "count": 3,
        "current_page": 1,
        "from": 1,
        "last_page": 12,
        "path": "https://api.yombo.net/api/v1/commands",
        "per_page": 3,
        "to": 3,
        "total": 34,
        "includable": [
            "users"
        ]
    },
    "links": {
        "first": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=1",
        "last": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=12",
        "prev": null,
        "next": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=2",
        "self": "https://api.yombo.net/api/v1/commands"
    }
}

GET - Specific command

Retrieve a specific command id.

Request URL

  • GET https://api.yombo.net/api/v1/commands/{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..." \
https://api.yombo.net/api/v1/commands/pVZQKBg9yzTd0glM7

  <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/commands/pVZQKBg9yzTd0glM7
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;">

{
    "data": {
        "type": "commands",
        "id": "pVZQKBg9yzTd0glM7",
        "attributes": {
            "id": "pVZQKBg9yzTd0glM7",
            "voice_cmd": "close",
            "machine_label": "close",
            "label": "Close",
            "description": "Sends a close command",
            "public": 2,
            "status": 1,
            "created_at": 1482065387,
            "updated_at": 1482065387
        },
        "links": {
            "self": "https://api.yombo.net/api/v1/commands/pVZQKBg9yzTd0glM7"
        }
    },
    "links": {
        "self": "https://api.yombo.net/api/v1/commands/pVZQKBg9yzTd0glM7"
    },
    "meta": {
        "includable": [
            "users"
        ]
    }
}

POST - Create new command

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

Request URL

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

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 command.
description string A detailed description of what the command 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": "Disabler", "machine_name": "disabler", "description": "Disables something. This is a test command for demonstration."}' \
https://api.yombo.net/api/v1/commands

  <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/commands'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "machine_name": "disabler",
    "label": "Disabler",
    "description": "Disables something. This is a test command 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;">

{
    "data": {
        "type": "commands",
        "id": "krb1qXmmkyH1X0KyP",
        "attributes": {
            "id": "krb1qXmmkyH1X0KyP",
            "voice_cmd": "voice test",
            "machine_label": "mitch_command1",
            "label": "Mitch command1",
            "description": "A mitch command...",
            "public": 1,
            "status": 1,
            "created_at": 1554858883,
            "updated_at": 1554858883
        },
        "links": {
            "self": "https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP"
        }
    },
    "links": {
        "self": "https://api.yombo.net/api/v1/commands"
    },
    "meta": {
        "includable": [
            "users"
        ]
    }
}

PUT / PATCH - Update a command

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

Request URL

  • PATCH https://api.yombo.net/api/v1/commands/{command_id}
  • PUT https://api.yombo.net/api/v1/commands/{command_id}

Parameters

See post new command 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 '{"label": "Disabler2", "description":
"Disables something. Even faster This is a test command for demonstration."}' \
https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP

  <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/commands/krb1qXmmkyH1X0KyP'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "label": "Disabler2",
    "description": "Disables something. Even faster This is a test command for demonstration.",
    }

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;">

{
    "data": {
        "type": "commands",
        "id": "krb1qXmmkyH1X0KyP",
        "attributes": {
            "id": "krb1qXmmkyH1X0KyP",
            "voice_cmd": "voice test",
            "machine_label": "mitch_command222",
            "label": "Mitch 1121266",
            "description": "A mitch command...",
            "public": 1,
            "status": 1,
            "created_at": 1554858883,
            "updated_at": 1554858962
        },
        "links": {
            "self": "https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP"
        }
    },
    "links": {
        "self": "https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP"
    },
    "meta": {
        "includable": [
            "users"
        ]
    }
}

DELETE - Delete a command

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

Request URL

  • DELETE https://api.yombo.net/api/v1/commands/{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/commands/krb1qXmmkyH1X0KyP

  <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/commands/krb1qXmmkyH1X0KyP'
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;">

{
    "data": {
        "type": "commands",
        "id": "krb1qXmmkyH1X0KyP",
        "attributes": {
            "id": "krb1qXmmkyH1X0KyP",
            "voice_cmd": "voice test",
            "machine_label": "mitch_command1",
            "label": "Mitch command1",
            "description": "A mitch command...",
            "public": 1,
            "status": 2,
            "created_at": 1554858883,
            "updated_at": 1554858909
        },
        "links": {
            "self": "https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP"
        }
    },
    "links": {
        "self": "https://api.yombo.net/api/v1/commands/krb1qXmmkyH1X0KyP"
    },
    "meta": {
        "includable": [
            "users"
        ]
    }
}

GET - Meta Information

Get the current meta information. Used for sorting, filtering, and relations.

Request URL

  • GET https://api.yombo.net/api/v1/commands/meta}

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/commands/meta

  <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/commands/meta'
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;">

{
    "data": {
        "type": "commands_meta",
        "id": "commands_meta",
        "attributes": {
            "sortable": [
                "voice_cmd",
                "machine_label",
                "label",
                "public",
                "status",
                "created_at",
                "updated_at"
            ],
            "includable": [
                "users"
            ],
            "filterable": [
                "user_id",
                "original_user_id",
                "voice_cmd",
                "machine_label",
                "label",
                "public",
                "status",
                "created_at",
                "updated_at"
            ]
        }
    }
}
Retrieved from "https://yombo.net/w/index.php?title=API:Commands&oldid=15140"