Filtering and Sorting

Overview

For endpoints that return collections, filtering and sorting are done by passing in a query object through the URL query parameter q. This page will describe what goes into the query parameter object and how to build it out.

Filtering

The primary method of filtering is done by using what is known as predicates.

Attributes are compounded with predicates to determine what information to match. For instance, the eq predicate can check to see if an attribute called name equals a value:

name_eq: 'Sea Monkey'

Note that the key is the attribute and filter predicate compound, and the value is the filter parameter.

A full list of predicates can be found here. You can find the list of filterable attributes in each endpoint's documentation.

Sorting

By default, objects are returned sorted by their database ID. To change this, you add the s key to the query object. The value is the field you want to sort by, followed by the order (asc for ascending, or desc for descending):

s: 'name asc'

URL parameter structure (with example)

The URL representation of the query object uses bracket notation: q[key]=value.

For example, let's say we wanted a filter for roadmaps that have "Ship" in their name and were created on or after January 1st, 2023, sorted by name ascending. The query object would look like:

{
  name_cont: "Ship",
  created_at_gteq: "2023-01-01",
  s: "name asc"
}

The query string representation of this would then be:

?q[name_cont]=Ship&q[created_at_gteq]=2023-01-01&q[s]=name+asc

When using JavaScript to create such a request, a matching jQuery request could look like this:

JavaScript

$.ajax({
  url:  "/api/v2/roadmaps",
  data: {
    q: {
      name_cont: "Ship",
      created_at_gteq: "2023-01-01",
      s: "name asc"
    }
  },
  success: function (data) {
    console.log(data);  
  }
});