API: Filtering

From Yombo
Jump to: navigation, search

Overview

See also

The filter query parameters can be used to filter results by partial property value, exact property value or if a property value exists in a given array of values.

Syntax

Filtering is specified in the query string with the filter argument, followed by the value you wish to search for. See the examples section for full syntax with examples.

All filters have wildcards before and after the value being searched.

Examples

A single field filter with a single value.

  • GET /api/v1/commands?filter[label]=on
    • This will return any records where the value 'on' is in the field 'label'. This will match 'on', 'fan_on', etc.

Multiple values can be included in the filter by separating them with a comma. The following example looks for on or off anywhere within the label field.

  • GET /api/v1/commands?filter[label]=on,off
    • This will return any records where the value 'on' or 'off' is in the field 'label'. This will match 'on', 'fan_on', 'off', etc.

Multiple field filters can be specified. This example defeats the purpose of 'off' within the multiple value selection, this is for demonstration purposes.

  • GET /api/v1/commands?filter[label]=on,off&filter[machine_label]=on
    • This will return any records where the value 'on' or 'off' is in the field 'label', and 'on' is within the machine_label.
  <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" \
https://api.yombo.net/api/v1/commands?filter[label]=on,off&filter[machine_label]=on
  <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?filter[label]=on,off&filter[machine_label]=on'
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;">
 1 {
 2     "data": [
 3         {
 4             "type": "commands",
 5             "id": "6a7ylqea1LsDqXb8V",
 6             "attributes": {
 7                 "id": "6a7ylqea1LsDqXb8V",
 8                 "voice_cmd": "on",
 9                 "machine_label": "on",
10                 "label": "On",
11                 "description": "Sends an on command",
12                 "public": 2,
13                 "status": 1,
14                 "created_at": 1482065387,
15                 "updated_at": 1518130546
16             },
17             "links": {
18                 "self": "https://api.yombo.net/api/v1/commands/6a7ylqea1LsDqXb8V"
19             }
20         },
21         {
22             "type": "commands",
23             "id": "2QRjY037VJcX0w6x9",
24             "attributes": {
25                 "id": "2QRjY037VJcX0w6x9",
26                 "voice_cmd": "fan on",
27                 "machine_label": "fan_on",
28                 "label": "Fan On",
29                 "description": "Turns on a fan, typically used by thermostat devices. ",
30                 "public": 2,
31                 "status": 1,
32                 "created_at": 1482065387,
33                 "updated_at": 1482065387
34             },
35             "links": {
36                 "self": "https://api.yombo.net/api/v1/commands/2QRjY037VJcX0w6x9"
37             }
38         }
39     ],
40     "meta": {
41         "count": 2,
42         "current_page": 1,
43         "from": 1,
44         "last_page": 1,
45         "path": "https://api.yombo.net/api/v1/commands",
46         "per_page": 5,
47         "to": 2,
48         "total": 2,
49         "includable": [
50             "users"
51         ]
52     },
53     "links": {
54         "first": "https://api.yombo.net/api/v1/commands?filter%5Blabel%5D=on%2Coff&filter%5Bmachine_label%5D=on&page%5Bnumber%5D=1",
55         "last": "https://api.yombo.net/api/v1/commands?filter%5Blabel%5D=on%2Coff&filter%5Bmachine_label%5D=on&page%5Bnumber%5D=1",
56         "prev": null,
57         "next": null,
58         "self": "https://api.yombo.net/api/v1/commands"
59     }
60 }
This page was last edited on 11 April 2019.