Result specifications are used by the Data_API to describe the desired results of a :py~buildbot.data.connector.DataConnector.get call. They can be used to filter, sort and paginate the contents of collections, and to limit the fields returned for each item.
Python calls to :py~buildbot.data.connector.DataConnector.get call can pass a :pyResultSpec instance directly. Requests to the HTTP REST API are converted into instances automatically.
Implementers of Data API endpoints can ignore result specifications entirely, except where efficiency suffers. Any filters, sort keys, and so on still present after the endpoint returns its result are applied generically. :pyResultSpec instances are mutable, so endpoints that do apply some of the specification can remove parts of the specification.
Result specifications are applied in the following order:
- Field Selection (fields)
- Filters
- Order
- Pagination (limit/offset)
- Properties
Only fields & properties are applied to non-collection results. Endpoints processing a result specification should take care to replicate this behavior.