Appearance

Querying in Truto API ​

This doc walks you through the various query parameter formats and conventions used in Truto API, both Admin and Unified APIs.

Unified, Admin and SuperQuery APIs ​

The following query parameter formats and operators can be used in the Unified, Admin and SuperQuery APIs.

Strings ​

If you are specifying a query parameter which accepts a string, then use the parameter name as is.

For example, if you are specifying a query parameter name with value foo, then the query parameters will be,

http
name=foo
json
{
  "name": "foo"
}

Numbers ​

If you are specifying a query parameter which accepts a number, then use the parameter name as is.

For example, if you are specifying a query parameter limit with value 10, then the query parameters will be,

http
limit=10
json
{
  "limit": 10
}

Booleans ​

If you are specifying a query parameter which accepts a boolean, then use the parameter name as is.

For example, if you are specifying a query parameter is_active with value true, then the query parameters will be,

http
is_active=true
json
{
  "is_active": true
}

Objects ​

If you are specifying a query parameter which accepts an object, then use [] brackets to specify the attributes.

Assuming the following query in JSON,

json
{
  "foo": {
    "bar": "baz",
    "bar1": {
      "bar2": "baz2"
    }
  }
}

The equivalent query parameters in HTTP request will be,

http
foo[bar]=baz&foo[bar1][bar2]=baz2

Arrays ​

If you are specifying a query parameter which accepts an array, then use empty [] brackets to specify the items.

Assuming the following query in JSON,

json
{
  "foo": [
    "bar",
    {
      "bar1": "baz1"
    }
  ]
}

The equivalent query parameters in HTTP will be,

http
foo[]=bar&foo[][bar1]=baz1

Date and Time ​

Date and time query parameters are specified in the ISO 8601 format regardless of the format the underlying third party API accepts. Truto handles the translation between the ISO 8601 format and the third party API format.

In all the Unified APIs we'll have the created_at and updated_at query parameters which can also use the gt, gte, lt, lte operators wherever the underlying API supports it.

WARNING

The operators you can use are dependent on the underlying API and if the underlying API doesn't support the operator, then Truto will ignore it.

For example, assuming you want to filter resources by created_at between 2021-01-01 and 2021-01-31, the query parameters will be,

http
created_at[gte]=2021-01-01T00:00:00Z&created_at[lte]=2021-01-31T23:59:59Z
json
{
  "created_at": {
    "gte": "2021-01-01T00:00:00Z",
    "lte": "2021-01-31T23:59:59Z"
  }
}

Sort by ​

If you want to sort the resources by a specific attribute, then use the sort_by query parameter.

WARNING

In case of Unified APIs, sorting will only work if the underlying API supports it and the attributes you can sort by is limited based on the underlying API.

For example, if you want to sort the resources by created_at in ascending order, the query parameters will be,

http
sort_by[created_at]=asc
json
{
  "sort_by": {
    "created_at": "asc"
  }
}

You can also sort by multiple attributes by specifying the sort_by query parameter multiple times.

For example, if you want to sort the resources by created_at in ascending order and then by updated_at in descending order, the query parameters will be,

http
sort_by[created_at]=asc&sort_by[updated_at]=desc
json
{
  "sort_by": {
    "created_at": "asc",
    "updated_at": "desc"
  }
}

Additional query operators in Admin and SuperQuery APIs ​

In the Admin and SuperQuery APIs, you can use the following additional query operators --

ne ​

The ne operator is used to filter resources where the attribute is not equal to the specified value.

For example, if you want to filter resources where the status attribute is not equal to closed, the query parameters will be,

http
status[ne]=closed
json
{
  "status": {
    "ne": "closed"
  }
}

eq ​

The eq operator is used to filter resources where the attribute is equal to the specified value.

For example, if you want to filter resources where the status attribute is equal to open, the query parameters will be,

http
status[eq]=open
json
{
  "status": {
    "eq": "open"
  }
}

in ​

The in operator is used to filter resources where the attribute is in the specified list of values.

For example, if you want to filter resources where the status attribute is either open or closed, the query parameters will be,

http
status[in][]=open&status[in][]=closed
json
{
  "status": {
    "in": ["open", "closed"]
  }
}

nin ​

The nin operator is used to filter resources where the attribute is not in the specified list of values.

For example, if you want to filter resources where the status attribute is neither open nor closed, the query parameters will be,

http
status[nin][]=open&status[nin][]=closed
json
{
  "status": {
    "nin": ["open", "closed"]
  }
}

like ​

The like operator is used to filter resources where the attribute matches the specified pattern.

For example, if you want to filter resources where the name attribute starts with foo, the query parameters will be,

http
name[like]=foo%
json
{
  "name": {
    "like": "foo%"
  }
}

nlike ​

The nlike operator is used to filter resources where the attribute does not match the specified pattern.

For example, if you want to filter resources where the name attribute does not start with foo, the query parameters will be,

http
name[nlike]=foo%
json
{
  "name": {
    "nlike": "foo%"
  }
}

gt, gte, lt, lte ​

The gt, gte, lt, lte operators are used to filter resources where the attribute is greater than, greater than or equal to, less than, and less than or equal to the specified value respectively.

For example, if you want to filter resources where the created_at attribute is greater than 2021-01-01 and lesser than 2021-01-31, the query parameters will be,

http
created_at[gt]=2021-01-01T00:00:00Z&created_at[lt]=2021-01-31T23:59:59Z
json
{
  "created_at": {
    "gt": "2021-01-01T00:00:00Z",
    "lt": "2021-01-31T23:59:59Z"
  }
}

or & and ​

The or and and operators are used to combine multiple query parameters.

For example, if you want to filter resources where the status attribute is open or name matches a pattern and the created_at attribute is greater than 2021-01-01, the query parameters will be,

http
or[0][status]=open&or[1][and][0][name][like]=foo%&or[1][and][1][created_at][gt]=2021-01-01T00:00:00Z
json
{
  "or": [
    {
      "status": "open"
    },
    {
      "and": [
        {
          "name": {
            "like": "foo%"
          }
        },
        {
          "created_at": {
            "gt": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  ]
}

In RapidBridge Sync Jobs ​

In RapidBridge Sync Jobs, query parameters can be specified in the query attribute of the resources array.

json
{
  "resources": [
    {
        "resource": "knowledge-base/page-content",
        "method": "list",
        "depends_on": "knowledge-base/pages",
        "query": {
            "foo": {
              "bar": "baz"
            },
            "baz": ["foo", "bar"],
            "created_at": {
              "gt": "2021-01-01T00:00:00Z"
            },
            "page_id": "{{resources.knowledge-base.pages.id}}"
        }
    }
  ]
}

You can use the object format to specify the query parameters in RapidBridge Sync Jobs. In the example above, the query parameters sent to the knowledge-base/page-content endpoint will be,

http
foo[bar]=baz&baz[]=foo&baz[]=bar&created_at[gt]=2021-01-01T00:00:00Z&page_id=123

You can also use the placeholders to refer to the values of other resources in the Sync Job. In the example above, the page_id query parameter refers to the id attribute of the knowledge-base/pages resource.

Remote Query Parameters ​

In Unified APIs, there are cases where you may need to pass query parameters to the underlying third-party API directly. In such cases, you can use the remote_query query parameter. The remote_query parameter is an object that contains the query parameters to be passed to the underlying third-party API.

You can use this parameter with any other unified query parameters and they will merged together with remote query parameters taking precedence.

Imagine a scenario where you want to pass the query parameters foo=bar and baz=foo to the underlying third-party API. The query parameters will be,

http
remote_query[foo]=bar&remote_query[baz]=foo
json
{
  "remote_query": {
    "foo": "bar",
    "baz": "foo"
  },
  //...any other unified query parameters
}

To specify this in the Truto Dashboards Try Unified API Modal, please check the Use code editor for query parameters checkbox and specify the query parameters in the code editor.

Remote Query Parameters