Skip to content

Searching: simple search

Simple search is using the GET method, and is accepting a set of basic query parameters for filtering, sorting, and limit/offset.

Filtering

Filtering parameters are appended as query parameters, e.g.
GET /assets/v1/host?customerID=1 will search for host assets for customer 1

Many filtering parameters accept multiple values, the default behaviour is to search for any of the provided values, e.g. GET /assets/v1/host?customerID=1&customerID=2 will search for host assets for customer 1 or 2.

Combining different search criteria generally has an AND logic, e.g.
GET /assets/v1/host?customerID=1&keywords=myhost will mean to search for hosts for customer 1 which also matches the keyword myhost.

See OpenAPI for valid filtering parameters.

Limit, offset and sorting

By default, any endpoint has a default limit of 25 elements : search endpoints (simple or advanced) will generally limit output to 25 rows, but allows user to override limit to get more/fewer rows, and set an offset to perform pagination.

The query parameters limit and offsetcan be added to override the defaults.

limit

By setting limit=0, the endpoint will perform an unlimited search, up to the system-defined maximum limit.

If the user sets a limit above the maximum limit, the endpoint will return an argument error.

If the user requests an unlimited search, which would return more than the system defined maximum limit, the endpoint will return HTTP 412 (argument error).

Currently, the system defined maximum result limit is 100000.

offset

By setting offset=X, the endpoint will return the number of results defined by limit, after skipping the first X entries.

Endpoints have a default sort order. To change the sorting, endpoints have a sortBy parameter, which allows changing the default sort property and direction, e.g.sortBy=id will sort by ID ascending, while sortBy=-id will sort by ID descending.

Adding multiple sortBy parameters will define a chained sorting order, e.g. sortBy=timestamp&sortBy=id will sort all entities by timestamp first, then by ID.

See OpenAPI for valid sorting parameters.

Examples:

  • limit=10 will return the first 10 results (as defined by the default sort order)
  • limit=10&offset=10will return the next 10 results after the 10 first results (as defined by the default sort order)
  • limit=10&sortBy=timestampwill return the first 10 results when ordered by timestamp
  • limit=0 will return all available results. If the requested search would return more than the system-defined limit, this will return an argument error.

Pagination

If fetching large amounts of data, using pagination can help speed up the process by conserving both client and system resources, and will give quicker response times.

By performing an initial search with a "moderate limit" (e.g. 1000 rows), the returned count allows the client to determine how much data there is to fetch, and paginate through it.

Example:

1
GET /assets/v1/host?customerID=1&limit=1000

may return :

1
{ "count":19350,"size":1000,"data":[...]}

Then, the client can perform 19 additional GEToperations to fetch the rest:

- GET /assets/v1/host?customerID=1&limit=1000&offset=1000 - GET /assets/v1/host?customerID=1&limit=1000&offset=2000 - GET /assets/v1/host?customerID=1&limit=1000&offset=3000 - ...