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
}

Parameter	Description	Format
<ParameterName1>	The attribute on which the filter applies	String
in	Receives a list of values (might be a list with one value), and the result must match exactly to at least one value	String Array
notIn	Receives a list of values (might be a list with one value), and the result must not match any of the values	String Array
eq	Receives a single value and the result must match it exactly	Integer
not	Returns only results that don’t have the value received (returns all results that have null value)	String
lt	Less than the number received, only applies for numerical type attributes	Integer
lte	Less than or equal to the number received, only applies for numerical type attributes.	Integer
gt	Greater than the number received, only applies for numerical type attributes.	Integer
gte	Greater than or equal to the number received, only applies for numerical type attributes.	Integer
like	The string received is a sub string of a result, only applies for string values.	String
from	Receives a time value and returns only results which have an equal or later date time value. Only applies for time value.	String
to	Receives a time value and returns only results which have an equal or earlier date time value. Only applies for time value.	String
isNull	Returns only results that have a null value	Boolean
isNotNull	Returns only results that have a value	Boolean

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"
}

Parameter	Description	Format
prop	The name of the parameter that the results will be sorted by	String
order	The order of the sorting that will apply. Can be ASC (Ascending Z⇾A) or DESC (Descending A⇾Z)	String

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.