Filtering

Data stored in API Resource endpoints can be filtered, or searched, by adding a query parameter to the request URL with the field set to the value you want to search on.

Limitations of Filtering

Filters can only currently support exact matches.

For example, if we want to search the dogs collection in the Pet Demo project for dogs that are of the breed "German Shephard", we would add the following to the request URL:

1
2
3
4
5
# filter
breed=German Shephard

# full URL
https://pet-demo.machinable.io/api/dogs?breed=German%20Shephard

Using the URL above with the filter on breed=German Shephard, the full request and response will look like the following:

1
2
curl -X GET \
  "https://pet-demo.machinable.io/api/dogs?breed=German%20Shephard"

1
2
3
4
5
6
7
8
9
import requests

url = "https://pet-demo.machinable.io/api/dogs?breed=German%20Shephard"

headers = {}

response = requests.request("GET", url, headers=headers)

print(response.text)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://pet-demo.machinable.io/api/dogs?breed=German%20Shephard");

xhr.send(data);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://pet-demo.machinable.io/api/dogs?breed=German%20Shephard"

    req, _ := http.NewRequest("GET", url, nil)

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))
}

Successful response: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
< HTTP/1.1 200 OK

{
    "count": 1,
    "items": [
        {
            "_metadata": {
                "created": 1552333754,
                "creator": "anonymous",
                "creator_type": "anonymous"
            },
            "age": 9,
            "breed": "German Shephard",
            "id": "5c86d3dda7748bb224833f68",
            "name": "Maximilian"
        }
    ],
    "links": {
        "self": "https://pet-demo.machinable.io/api/dogs?_limit=10&_offset=0&breed=German Shephard"
    }
}

The response count is the total count of results based on the filter.

Pagination will be based on the filter.