Using BioT Search APIs

BioT Search API is a generic API that exists in different services across the BioT platform.
It is used to retrieve information relating to the service it exists in. For the Device service, BioT Search API is used to search for devices and device related information. For the Organization service, BioT Search API is used to search for organizational users.

All the APIs follow the same structure, and the information in the following article relates to all of them. The API call is a simple GET request. The JSON structure explained here should be built and then URL encoded.

For example, if we want to use this search API:
https://api.dev.biot-med.com/device/v2/devices

• Request: GET
• URL https://example.com/device/v2/devices?searchRequest=<ENCODED_JSON_OBJECT>
• Body:

{
  "sort": [
    {
      "prop": "_name",
      "order": "ASC"
    }
  ],
  "limit": 10,
  "page": 3
}

The result of this API call will be as follows:

https://api.dev.biot-med.com/device/v2/devices?searchRequest=%7B%0A%20%20%22sort%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22prop%22%3A%20%22_name%22%2C%0A%20%20%20%20%20%20%22order%22%3A%20%22ASC%22%0A%20%20%20%20%7D%0A%20%20%5D%2C%0A%20%20%22limit%22%3A%2010%2C%0A%20%20%22page%22%3A%203%0A%7D

📘

Note

To test the URL, use URL Encode Online.

Search JSON Structure Explained

The JSON is composed of optional parameters:

• filter
• freeTextSearch
• sort
• limit
• page

The following is an example of a JSON Structure:

{
  "filter": {
    "<ParameterName1>": {
      "in": [
        "string"
      ],
      "notIn": [
        "string"
      ],
      "eq": {},
      "lt": 0,
      "lte": 0,
      "gt": 0,
      "gte": 0,
      "like": "string",
      "from": "2022-06-29T07:30:52.900Z",
      "to": "2022-06-29T07:30:52.900Z",
      "isNull": true,
      "isNotNull": true,
      "not": {}
    },
    "<ParameterName2>": {
      "in": [
        "string"
      ],
      "notIn": [
        "string"
      ],
      "eq": {},
      "lt": 0,
      "lte": 0,
      "gt": 0,
      "gte": 0,
      "like": "string",
      "from": "2022-06-29T07:30:52.900Z",
      "to": "2022-06-29T07:30:52.900Z",
      "isNull": true,
      "isNotNull": true,
      "not": {}
    }
  },
  "freeTextSearch": "string",
  "sort": [
    {
      "prop": "<ParameterName3>",
      "order": "ASC"
    },
    {
      "prop": "<ParameterName4>",
      "order": "ASC"
    }
  ],
  "limit": 1,
  "page": 0
}

Filter

If a filter is sent, all the returned results conform to the filter’s rules.
Filters can be combined by adding more values as child fields to the filter field (e.g., additionalProp1 and addidionalProp2), multiple filters are combined with a logical AND. The default filter is empty (no filters).

The following is an example of a JSON Filter:

"<ParameterName1>": {
      "in": [
        "string"
      ],
      "notIn": [
        "string"
      ],
      "eq": {},
      "not": {},
      "lt": 0,
      "lte": 0,
      "gt": 0,
      "gte": 0,
      "like": "string",
      "from": "2022-06-29T07:30:52.900Z",
      "to": "2022-06-29T07:30:52.900Z",
      "isNull": true,
      "isNotNull": true
}

Free Text Search

The free text search functions similarly to a filter, except it searches all fields simultaneously.

For example:

• If entity 1 is “foo”: ”my_value”
• If entity 2 is “bar”: ”my_value”

A search for “my_value” will return both entities.

All searchable fields are searched for with the free text search value. The value can be a substring of the entities value and the searchable fields themselves are determined on an entity basis. The default is null (no freeTextSearch)

See example here.

Sort

When a sort is sent, the results are sorted by it. Multiple sorts can be chained together and will work in the order they are sent in. The first sort is the primary sort, the second is the secondary sort, etc...
The secondary sort (and subsequent sorts) change the sorting of results only when the sort one level above them has multiple results with the same value in the sorted attribute.
The default sort is the entity creationTime DESC.

The following is an example of a Sort JSON Structure:

{
    "prop": "<ParameterName3>",
    "order": "ASC"
}

Limit

The maximum amount of results to show in each result page. This limit is used for pagination and splits the results in chunks, so there won't be one big response but multiple small ones. The default is 100.

🚧

Raising the limit

It is possible to raise the limit of 100 results for a search request.
You need to take into account that going over this limit might have unexpected result.
It is strongly recommended to use the limit and paginate the API calls until all the required results are obtained.

Page

The page number to show in the pagination. The "limit" and "page" are used together, so if you state a limit of 10 with a page of 3, then you will receive the search results records 30-40. The default is 0.