Range expressions are a powerful way to filter certain API endpoints. Typically, they apply to the primary key of a resource.
- A range expression allows to you pass values in multiple ways. Let's use the
GET /api/v2/discussions endpoint as an example. - The
discussionID parameter on this endpoint supports range expressions.
Query a single ID
You can use a range expression to query a single ID. This example will fetch just discussion 100.
Example
GET /api/v2/discussions?discussionID=100
Query an array of IDs
You can query a fixed array of IDs with a CSV or query-string array notation. These examples will fetch discussions 100 and 150.
Examples
// CSV notation
GET /api/v2/discussions?discussionID=100,150
// Array notation
GET /api/v2/discussions?discussionID[]=100&discussionID[]=150
Query a range of IDs
A range of IDs may be fetched via a few notations.
Query every discussionID greater than or equal to 100
// Dot notation
GET /api/v2/discussions?discussionID=100..
// <= notation
GET /api/v2/discussions?discussionID=>=100
// > notation
GET /api/v2/discussions?discussionID=>99
Query every discussionID less than or equal to 100
// Dot notation
GET /api/v2/discussions?discussionID=..100
// >= notation
GET /api/v2/discussions?discussionID=<=100
// < notation
GET /api/v2/discussions?discussionID=<101
Query a range between 100 and 150
// Dot notation
GET /api/v2/discussions?discussionID=100..150
// Inclusive brackets
GET /api/v2/discussions?discussionID=[100,150]
// Exclusive brackets
GET /api/v2/discussions?discussionID=(99,151)
// Mixed brackets
GET /api/v2/discussions?discussionID=[100,151)
Missing records with range expressions
If you used GET /api/v2/discussions/100 but did not have permission to access the discussion with ID 100 or it did not exist, the API would return an error code with either a permission error or a not found error.
However, GET /api/v2/discussions?discussionID=100 and GET /api/v2/discussions?discussionID=(99,101) will return an empty result set with no error in the same scenarios.
Why? Because range expressions are simply a filter. This makes sense if you think of the following scenario:
- There are three discussions [99, 100, 101].
GET /api/v2/discussions?discussionID=99..101 will return three results.- I delete discussion 100.
GET /api/v2/discussions?discussionID=99..101 will now return two results.
It is possible, and even common, for there to be holes in ID ranges, so no errors are returned.