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 API documentation 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 API documentation for valid sorting parameters.
Examples:#
limit=10will 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 timestamplimit=0will 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:#
GET /assets/v1/host?customerID=1&limit=1000
may return :
{ "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=1000GET /assets/v1/host?customerID=1&limit=1000&offset=2000GET /assets/v1/host?customerID=1&limit=1000&offset=3000…