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

Parameter

Description

Format

<ParameterName1>

The attribute on which the filter applies

String

in

Receives a list of values (maybe a list with one value), and the result must match exactly to at least one value

String

eq

Receives a single value and the result must match it exactly

Integer

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

not

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

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.

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.


Did this page help you?