Skip to main content

​
Overview

List endpoints in the Boomerang Developer API use . This keeps requests simple, predictable, and easy to integrate with typical back-end and reporting tools. This page explains:
  • Standard pagination parameters
  • Response structure and metadata
  • Ordering guarantees
  • Validation and error behaviour
  • Recommended client patterns
Concrete, endpoint-specific examples are documented alongside each list endpoint.

​
Request parameters

All paginated endpoints accept a common set of query parameters:
  • page – 1-based page number.
  • per_page – number of items to return per page.
Defaults and limits:
  • If page is not provided, it defaults to 1.
  • If per_page is not provided, it defaults to 25.
  • There is a maximum per_page value enforced by each endpoint to protect performance; values above the maximum are treated as invalid and return a validation error.
General rules:
  • page must be a positive integer.
  • per_page must be a positive integer within the allowed range for that endpoint.
  • Pagination is applied after any filters and sorting options in the request.

​
Response structure

Paginated endpoints return a top-level collection and a pagination object with metadata. Example shape: 
{
  "items": [
    {
      "id": "example-1"
      // ...
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 123,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false,
    "next_page": 2,
    "prev_page": null
  }
}
Field semantics:
  • items – array of items for the current page.
  • pagination.page – current page number.
  • pagination.per_page – number of items requested per page.
  • pagination.total – total number of matching items for this query.
  • pagination.total_pages – total number of pages for this query.
  • pagination.has_next / has_prev – booleans indicating whether there are adjacent pages.
  • pagination.next_page / prev_page – page numbers for adjacent pages (or null when not applicable).
For some high-volume endpoints, pagination.total may be approximate or omitted if calculating an exact count would be too expensive; this will be documented per endpoint if applicable.

​
Ordering and consistency

By default, paginated lists are ordered with the newest items first, typically based on a creation or update timestamp. Key points:
  • Unless an endpoint provides a specific order_by or sort parameter, clients should assume:
    • A stable, documented default ordering (newest-first); but
    • No guarantee that ordering cannot change if the definition of “newest” is clarified or a tie-breaking rule is added.
  • Pagination is based on the result set after applying filters and sorting, so changes to filters or sort options will change which items appear on a given page.
To improve resilience:
  • Do not rely on a specific item always appearing on a specific page number.
  • Where possible, design clients to work with items as sets rather than hard-coding page numbers.

​
Validation and error behaviour

Invalid pagination parameters are treated as request errors:
  • If page or per_page is non-numeric, negative, zero, or above the allowed maximum, the API returns:
    • HTTP status 400 Bad Request
    • Error code 1001 (VALIDATION_FAILED)
    • A details.hint indicating which parameter is invalid.
Example error shape (conceptual): 
{
  "status": "VALIDATION_FAILED",
  "code": 1001,
  "http_status": 400,
  "method": "GET",
  "path": "/v1/example",
  "timestamp": 1763205835591,
  "trace_id": "…",
  "details": {
    "message": "One or more request parameters are invalid.",
    "hint": "`per_page` must be a positive integer up to the documented maximum."
  }
}
When a requested page is beyond the available range (for example, page is greater than total_pages):
  • The API returns a successful response (200 OK) with:
    • items: []
    • has_next: false
    • An appropriate pagination block indicating the request context.
This avoids treating “no more results” as an error condition.

​
Usage guidance

Recommended patterns for clients:
  • Start from page 1 Begin with page=1 and iterate until has_next is false if you need to walk the entire result set.
  • Avoid excessive per_page values Use moderate per_page values for interactive use (for example, dashboards) and only larger values where necessary for back-end tasks.
  • Do not assume fixed membership per page Underlying data can change between requests. Items may move between pages or disappear as they are added, updated, or removed.
  • Use filters to narrow result sets Prefer tighter filters over very large page sizes when you only need a subset of data.
Pagination behaviour is consistent across modules to keep integration simple and predictable. Any endpoint-specific deviations or additional fields will be documented with that endpoint.