API Pagination & Filtering

Most endpoints that return a list of entities need some pagination and filtering. Without pagination, a simple search could return hundreds of thousands or even millions of hits.

NebularStack API mostly follows a standard design for filtering, sorting, and pagination, unless stated otherwise by the endpoint specification.

There are some constraints, such as a maximum of 50 entities per page. For example, a page is just one set of results returned out of several pages up to a maximum of 250 entities over 10 pages. We also differentiate searching from filtering, which is also documented here.

Example API Response:

{
    "payload": [
        {
            ... entity1 ...
        },
        {
            ... entity2 ...
        },
    ],
    "metadata": {
        "records": 2,
        "page": 1,
        "pages": 1,
        "per_page": 10
    }
}

records is the total entities found, limited to 250.
page is the current page.
pages is the total pages found.
per_page should be equal to limit.

Filtering

Filtering is only supported on a set of properties as per API Spec. URL parameters are the easiest way to filter using the property names.

An Example:

/v1/subscribers?username=testing*

Constraints:

Unknown or unsupported properties in the query string will silently be ignored.

Sorting is silently ignored when filtering.

When using wildcard (*) a minimum of 3 characters is required.

Wildcard is only supported at the end of the filter value.

Sorting

Only properties that support filtering can be sorted, and only one property can be sorted per request. These properties are documented per API Spec.

Query String parameters:

sc name of property to sort by. (sort property/column)
sd with following values. (sort direction):
- asc - ascending
- desc - descending

When sorting both query parameters MUST be included for example:

/v1/subscribers?sc=username&sd=desc

Pagination

The default limit set per page is 10, which results in a maximum of 250 pages.

The following query parameters are supported:

l: Result Limit (default 10)
p Pagination Page (default 0)

An example:

/v1/subscribers?l=10&p=2

When supported by the specific endpoint view, you can return all entities by setting the limit to 0. Generally speaking, most API views support -1, which is streaming. Streaming also returns all the entities.

The streaming response differs from the original response example:

{"property1": "value1", "property2": "value2"}\n
{"property1": "value1", "property2": "value2"}\n
{"property1": "value1", "property2": "value2"}\n

As per above, each object will be separated by a new line and not encapsulated in an Array.

More information can be found on the API Guidelines > Limitations > Listing Objects.

Searching

Searching is also only supported by specific endpoint views as per API Spec.