API: API Key

From Yombo
Jump to: navigation, search

Summary

An API Application Key is used to authorize applications, this is separate from the user. This allows Yombo to revoke applications access to the API if they are behaving badly.

The API App Key (AKA: API Key) must be sent with all requests for the service to accept the request. There are two methods to submit the API App Key:

  1. In the HTTP request header as: x-api-app-key
    • Alternatives include: x-api-key, x_api_app_key, x_api_key, and api_app_key
    • Example: x-api-key: abc123xyz789
  2. In the query string, use any of the above names as a query string parameter.
    • Example: https://api.yombo.net/api/v1/commands?x-api-app-key=abc123xyz789

You must replace abc123xyz789 with a valid API App Key.

Currently, you can request an API key by emailing support at yombo.net with a description for the usage of the API key. The ability to add API Keys through my.yombo.net is planned.

The API key is not used to authenticate the user, only the application. For authentication, see API Authentication to authenticate the user.

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