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. case insensitive | 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.
Updated 11 days ago