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 Decode 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"
      ],
      "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"
      ],
      "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"
      ],
      "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": {}
}
ParameterDescriptionFormat
<ParameterName1>The attribute on which the filter appliesString
inReceives a list of values (maybe a list with one value), and the result must match exactly to at least one valueString
eqReceives a single value and the result must match it exactlyInteger
ltLess than the number received, only applies for numerical type attributesInteger
lteLess than or equal to the number received, only applies for numerical type attributes.Integer
gtGreater than the number received, only applies for numerical type attributes.Integer
gteGreater than or equal to the number received, only applies for numerical type attributes.Integer
likeThe string received is a sub string of a result, only applies for string values.String
fromReceives a time value and returns only results which have an equal or later date time value. Only applies for time value.String
toReceives a time value and returns only results which have an equal or earlier date time value. Only applies for time value.String
isNullReturns only results that have a null valueBoolean
isNotNullReturns only results that have a valueBoolean
notReturns only results that don’t have the value received (returns all results that have null value)Strig

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)

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"
}
ParameterDescriptionFormat
propThe name of the parameter that the results will be sorted byString
orderThe 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.

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.