API
  • API Index
  • Batch API
  • Content Negotiation
  • Dynamic Paths
  • Hierarchy API
  • List API
  • Quick Reference
  • Time Series API
  • Views
      • Configuration
  • Overview
  • Application Configuration
  • Documentation Configuration
  • Spec Configuration
      • Features
  • API Testing
  • Asynchronous Processing
  • Cassandra Time-Series Engine
  • Cassandra Integration
  • Default Controller Customisation
  • Documentation
  • Geospatial Filtering
  • Model Documentation
  • PostgreSQL Integration
  • Excel Spreadsheet Format
      • Tutorials
  • Step-by-Step Guide
  • Archetype Setup
  • Logging
  • Prometheus
  • Sentry Logging
      • UI Customisation
  • UI Customisation
  • SASS Build Chain
  • Shared Layout
  • API Documentation
  • Model Documentation
  • Results
    • sapi-nt v current

    List API

    List endpoints return descriptions for lists of resources. They support the following features:

    Sorting

    You can sort results by the values of specific properties by supplying the _sort query parameter. The value of the parameter should be a property name or dot-separated property path, similarly to filter parameters. The sorting uses the natural ascending order of the values.

    You can use sorting along with paging to page through the full set of results without requesting all of them at once.

    For example to sort by the “label” of a related “region”:

    _sort=region.label

    You can sort by multiple properties by supplying multiple values for the _sort parameter. If you do, the sorting will be applied in the order in which you specify the values.

    For example, to sort first by the type, then by the label of each resource:

    _sort=type&_sort=label

    To sort by the resource URI, set the value of _sort to the ID token, @id.

    Sort Direction

    You can also sort by the descending order of the values by prepending the - character to the _sort parameter value. You can also optionally prepend the + character to denote the normal ascending order, although this is not necessary.

    For example, to sort by type descending, then by the label ascending:

    _sort=-type&_sort=label

    Paging

    You can request sub-lists of results by supplying the following parameters:

    Parameter Description
    _limit Maximum number of results to return.
    _offset Number of initial results to skip.

    Usually, list endpoints have a default result limit (or “soft limit”). However, you can override this by supplying the _limit parameter. They may also have a “hard limit” which is used if the requested limit exceeds it.

    For example, to access the first 100 results:

    _limit=100

    And then the second 100 results:

    _limit=100&_offset=100

    If you are paging results in this way, you should also specify a unique ordering (eg. _sort=@id to sort by URI) to make sure that no results are skipped or repeated.

    When you supply paging parameters, or when the API applies the soft limit, the metadata description in the response will include the limit and/or offset value.