Extend hawkBit Documentation (#2920)
This commit is contained in:
Desislava Marinova
committed by
GitHub
GitHub
parent
30fd475b57
commit
a82f4cc9f6
132
docs/query-parameters.md
Normal file
132
docs/query-parameters.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# Query Parameters
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Sorting](#sorting)
|
||||
- [Paging](#paging)
|
||||
- [Examples](#examples)
|
||||
- [FIQL Syntax Search Query](#fiql-syntax-search-query)
|
||||
- [Basic operators and composite operators at a glance](#basic-operators-and-composite-operators-at-a-glance)
|
||||
- [Basic operators](#basic-operators)
|
||||
- [Composite operators](#composite-operators)
|
||||
- [Using wildcards to filter](#using-wildcards-to-filter)
|
||||
- [Combining Sorting, Paging, and FIQL](#combining-sorting-paging-and-fiql)
|
||||
|
||||
## Sorting
|
||||
|
||||
The `sort` query parameter defines the sort order for query results.
|
||||
|
||||
A sort criteria includes a field name and direction (`ASC` ascending or `DESC` descending).
|
||||
|
||||
Multiple criteria can be used, defining the sort order of entities in the result.
|
||||
|
||||
**Syntax:**
|
||||
|
||||
| Parameter | Value |
|
||||
|-----------|-------|
|
||||
| sort | sort_criteria {"," sort_criteria} |
|
||||
| sort_criteria | field_name ":" ("ASC"\|"DESC") |
|
||||
| field_name | alpha |
|
||||
| alpha | (digit\|character){digit\|character}; |
|
||||
| digit | "0"\|"1"\|"2"\|"3"\|"4"\|"5"\|"6"\|"7"\|"8"\|"9"; |
|
||||
| character | lowercase_character\|uppercase_character\|special_character |
|
||||
| special_character | "_" |
|
||||
| lowercase_character | "a"\|"b"\|"c"\|"d"\|"e"\|"f"\|"g"\|"h"\|"i"\|"j"\|"k"\|"l"\|"m"\|"n"\|"o"\|"p"\|"q"\|"r"\|"s"\|"t"\|"u"\|"v"\|"w"\|"x"\|"y"\|"z"; |
|
||||
| uppercase_character | "A"\|"B"\|"C"\|"D"\|"E"\|"F"\|"G"\|"H"\|"I"\|"J"\|"K"\|"L"\|"M"\|"N"\|"O"\|"P"\|"Q"\|"R"\|"S"\|"T"\|"U"\|"V"\|"W"\|"X"\|"Y"\|"Z"; |
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
/targets?sort=field_1:ASC,field_2:DESC,field_3:ASC
|
||||
```
|
||||
|
||||
## Paging
|
||||
|
||||
Pagination is automatically applied to all GET requests for collection resources.
|
||||
|
||||
**Configuration parameters:**
|
||||
|
||||
- `offset`: paging offset (default is 0)
|
||||
- `limit`: maximum entries per page (default is 50)
|
||||
|
||||
The maximum value for `limit` is 500. For groups, the maximum is 1000 (subject to change in future versions).
|
||||
|
||||
Invalid values default to standard settings. Limits exceeding the maximum use the maximum value instead.
|
||||
|
||||
### Examples
|
||||
|
||||
| URL | Description |
|
||||
|-----|-------------|
|
||||
| `/targets?sort=name:ASC` | Sorts targets by name, returns first 50 (default offset 0, default limit 50) |
|
||||
| `/targets?sort=name:ASC&limit=10` | Sorts targets by name, returns first 10 |
|
||||
| `/targets?sort=name:ASC&offset=10` | Sorts targets by name, returns next 50 targets after the 10th (starting with 11th) |
|
||||
| `/targets?sort=name:ASC&offset=20&limit=10` | Sorts targets by name, returns next 10 targets after the 20th (starting with 21st) |
|
||||
| `/targets?sort=name:ASC&offset=100&limit=600` | Sorts targets by name, returns next 500 targets (max limit, not 600) after the 100th (starting with 101st) |
|
||||
|
||||
## FIQL Syntax Search Query
|
||||
|
||||
The `q` parameter filters resource fields using Feed Item Query Language (FIQL).
|
||||
|
||||
**Syntax:**
|
||||
|
||||
```
|
||||
q=FIQL-expression
|
||||
```
|
||||
|
||||
**Expression structure:**
|
||||
|
||||
```
|
||||
q=field<basic_operator>value<composite_operator>field<basic_operator>value<...>
|
||||
```
|
||||
|
||||
- `q`: identifier for FIQL query
|
||||
- `field`: resource field name (see Entity definitions for filterable fields)
|
||||
- `value`: field value
|
||||
- `<basic_operator>`: operators for simple queries
|
||||
- `<composite_operator>`: operators to join simple queries
|
||||
|
||||
### Basic Operators and Composite Operators at a Glance
|
||||
|
||||
#### Basic Operators:
|
||||
|
||||
| Operator | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `==` | Equal to expression | `/targets?q=name==ccu299792` |
|
||||
| `!=` | Not equal to expression | `/targets?q=name!=ccu299792` |
|
||||
| `=lt=` | Less than expression | `/distributionsets?q=id=lt=142` |
|
||||
| `=le=` | Less than or equal expression | `/distributionsets?q=id=le=142` |
|
||||
| `=gt=` | Greater than expression | `/distributionsets?q=id=gt=142` |
|
||||
| `=ge=` | Greater than or equal expression | `/distributionsets?q=id=ge=142` |
|
||||
| `=li=` | Like expression | `/targets?q=name=li=_________0` |
|
||||
| `=in=` | In expression | `/targets?q=name=in=(ccu299792, shc137)` |
|
||||
| `=out=` | Not in (out) expression | `/targets?q=name=out=(ccu299792, shc137)` |
|
||||
|
||||
#### Composite Operators:
|
||||
|
||||
| Operator | Description | Example |
|
||||
|--------------|-------------|-------------------------------------------------------------------|
|
||||
| `and` or `;` | AND expression | `/rest/v1/targets?q=updatestatus==unknown and controllerId==SHC*` |
|
||||
| `or` or `,` | OR expression | `/rest/v1/targets?q=updatestatus==unknown or updatestatus==error` |
|
||||
|
||||
### Using Wildcards to Filter
|
||||
|
||||
Use `*` for wildcard matches.
|
||||
|
||||
| Example URL | Description |
|
||||
|-------------|-------------|
|
||||
| `/targets?q=name==ccu*` | Returns targets with names starting with ccu |
|
||||
| `/targets?q=name==*ccu` | Returns targets with names ending with ccu |
|
||||
| `/targets?q=name==*ccu*` | Returns targets containing ccu in their name |
|
||||
| `/targets?q=name=="ccu\\*"` | Returns targets with names starting with ccu* |
|
||||
| `/targets?q=name=="*\\*\*"` | Returns targets containing asterisk(*) in their names |
|
||||
|
||||
### Combining Sorting, Paging, and FIQL
|
||||
|
||||
| Example URL | Description |
|
||||
|-----------------------------------------------------------------------------------------------------|-------------|
|
||||
| `/targets?sort=controllerId:DESC&limit=5&q=updatestatus==pending` | Returns 5 targets with updatestatus 'pending', sorted descending |
|
||||
| `/softwaremodules?sort=name:ASC&q=version==5.1.1 and type==application` | Returns software modules sorted by name, with version 5.1.1 and type application |
|
||||
| `/distributionsets?sort=name:DESC&limit=150&q=name==*CCU* or description==*CCU*` | Returns 150 distribution sets sorted descending by name with CCU in name or description |
|
||||
| `/distributionsettypes?limit=100&offset=100&q=key==vhicletypex2015` | Returns 100 distribution set types (starting with 101st) with key vhicletypex2015 |
|
||||
| `/targets?sort=name:ASC&offset=100&limit=25&q=(description==*SH* or name==*SH*) and name=li=_____` | Returns 25 targets (starting with 101st), sorted ascending, with 'SH' in name or description and exactly 5 characters |
|
||||
| `/targets?sort=name:DESC&limit=50&q=name=in=(*ccu*, *ecu*) and updatestatus=in=(pending, in\_sync)` | Returns 50 targets sorted descending with 'ccu' or 'ecu' in name and updatestatus 'pending' or 'in_sync' |
|
||||
Reference in New Issue
Block a user