REST API Sorting Paging and Filtering

Some REST API endpoints in Thrinacia support sorting, paging and filtering operations. These are controlled as per below.

Sorting

  1. Sorting is controlled via “sort” input parameter
  2. The field name can be optionally prefixed by “-” to indicate descending sort
  3. If the field is virtual (non-physical, but abstract calculated value) then we can use “*” to denote that
  4. If the value is not specified default sorting will be performed ( usually as “-created” )
  5. Multiple fields can be specified and delimited via “,” parameter
  6. All target fields must match first core entity being sorted ( no nested, second level sorting is supported yet )

Examples

Query Example Explanation
?sort=-created Sort via created field in descending order
?sort=created Sort via created field in ascending order
?sort=created,modified Sort in ascending order via created, then modified field
?sort=*-funded_percentage Sort via virtual field called funded_percentage in descending order
?sort=*funded_percentage Sort via virtual field called funded_percentage in ascending order

 

Paging

  1. Current page is controlled via “page” input parameter
  2. Number of entries shown per page is controlled via “page_entries” input parameter
  3. Default limit of results per page is currently 100
  4. Special response headers labeled with ‘X-Pager*’ are used to read the paging information
  5. The custom response headers used to display pages, page sets, etc.

 

Examples

Query Example Explanation
?page=2&page_entries=10 Go to page 2 and show 10 entries per page
?page=1 Go to page 1 and show 100 results per page
?page_entries=25 Go to page 1 and Show 25 results per page

 

Custom Paging Headers ( Response )

Header Name Description
X-Pager-Total-Entries Total entries for result set
X-Pager-Entries-Per-Page Number of entries per page
X-Pager-Current-Page Current Page Number
X-Pager-First-Page First Page Number of the Result Set
X-Pager-Last-Page Last Page Number of the Result Set
X-Pager-Previous-Page Previous Page Number of the Result Set
X-Pager-Next-Page Next Page Number of the Result Set
X-Pager-Pages-Per-Set Total Pages Per Result Set
X-Pager-Pages-In-Set Total Pages Inside the Result Set
X-Pager-Previous-Set-Page Previous Set Page Number
X-Pager-Next-Set-Page Next Set Page Number

 

Filtering

  1. Used to filter result set and narrow down result set or drill down into the results
  2. Controlled via special input parameter called “filters” containing JSON structure inside the value
  3. Multiple filters can be chained together inside the same JSON structure, simply add another filter field definition after first one
  4. Multiple value formats for each key are supported inside JSON structure including simple string/scalar, array or associative array ( key => value )

Filter Examples

Example #1 

campaign?filters={"backer":"5"}

Return all campaigns that were pledged on by person_id 5

Example #2 

campaign?filters={"category":"1", "location":"1"}

Return all campaigns that match category_id 1 and city_id 1 as the location

Example #3 

campaign?filters={"category":["1","2","3"]}

Return all campaigns that match either category_id: 1, 2 or 3

Example #4 

campaign?filters={"category":{"1":"true","2":"false"}}

Return all campaigns that match category_id 1 but not category_id 2

Example #5 

campaign?filters={"backer":["5","10"]}

Return all campaigns that match pledger being person_id 5 or 10

Example #6 

campaign?filters={"starts":{"range":["2018-01-01 10:00:00","2019-01-01 10:00:00"]}}

Return all campaigns that have start timestamp between 2018-01-01 10:00:00 and 2019-01-01 10:00:00