🔍NData query syntax
This section describes the query syntax used in PORTOS API, called "NData".
What is NData?
NData is custom syntax to perform server-side pagination, sorting, inclusion and filtering, inspired by open stack syntax.
Pagination
Pagination allows to specify range of items received from the API. Pagination can be implemented using one or both of two query parameters:
$skip
Skip
integer
Describing number of records to skip from beginning of result collection.
$take
Take
integer
Maximum count of items to be returned.
Pagination examples
$skip=10
Skip first 10 items and return rest.
$take=5
Return at most 5 items
| |
$skip=10&$take=5
or
$take=10&$skip=5
| Skip first 10 items and return _at most_ next 5 items. |
Sorting
Sorting allows to change order of returned items.
$sort
Sort
comma separated list of sort keys.
More than one sort key may be specified. If multiple keys are specified, result collection is sorted by keys in order given by this parameter.
The caller may (but is not required to) specify a sort direction for each key. If a sort direction is not specified for a key, then a default is set by the server. Sort directions can optionally be appended to each sort key, separated by the : character. Supported sort directions are:
Ascending
asc
This is an default sort direction.
Descending
desc
Alternatively, descending sort direction can be specified as prepended minus (-) character.
Sorting examples
$sort=value1,value2,value3
Sort by value1, then by value2, then by value3. Directions are defaulted by server.
$sort=value1,value2:desc
or
$sort=value1,-value2
| Sort by value 1, then sort by value2 descending. Sort direction for first value is defaulted by server. Please note the minus sign notation in second example. Both examples produces same result. | |
$sort=value1
and
$sort=value1,value1
| Multiple occurrence in query is supported, thus both queries are equal. | |
$sort=value1,value2:desc
and
$sort=value1,value2:DESC
| Sort descriptors are case insensitive. Both following queries are equal |
Inclusion
Inclusion allows to extend response format.
$include
Include
comma separated list of keys.
Allows to specify one or more members (that are not part of output by default) to be included in response.
Inclusion examples
$include=value
Single key is specified to be included in API response.
$include=value1,value2,value3
Multiple keys are specified to be included in API response.
Filtering
API endpoint-specific filters are often supported, to filter result based on provided filter values.
No global parameters are defined. Each endpoint-specific filter supports one or more parameters. Each parameter is identified by its name, below addressed as FILTER_MEMBER.
Filtering syntax: operations, operator and operation arguments
Value of each filter is semicolon-separated (;) list of operations.
Syntax:
FILTER_MEMBER=OPERATION1;OPERATION2
Each operation consists of segments delimited by colon (:) character. First segment is an operator, followed by 0 or more operation arguments.
Syntax:
FILTER_MEMBER=OPERATOR:OPERATION_ARGUMENT1:OPERATION_ARGUMENT2
Example: Filter member named "DiscountRate" is associated with single operation, that has "gt" operator and one operation argument, value 10. Result query is:
DiscountRate=gt:10
Multiple filter occurrence
Multiple occurrence of same filter member is supported, thus both following queries are equal:
DiscountRate=gt:0&DiscountRate=lt:50DiscountRate=gt:0;lt:50
Operators
Each filter may support one or more operators. Usually, well-known operators (listed below) are used. Each filter may, however, support custom operators - operators with custom name.
Well-known operators
eq
Equal
This is default operator, if not stated otherwise. Operation with this operator expects single operation argument.
| | `neq` | Not equal |
Specifies that filter member value must not be equal to provided operation argument. Operation with this operator expects single operation argument.
| | `in` | In | Specifies that filter member value must be equal to one of values provided in operation argument. Operation with this operator expects single _operation argument_ - the collection with one or more elements. | | `nin` | Not in | Specifies that filter member value must not be equal to any value provided in operation argument. Operation with this operator expects single _operation argument_ - the collection with one or more elements. | | `gt` | Greater than | Specifies that filter member value must be greater than value provided in operation argument. Operation with this operator expects single _operation argument_. | | `gte` | Greater than or equal to | Specifies that filter member value must be greater than or equal to value provided in operation argument. Operation with this operator expects single _operation argument_. | | `lt` | Less than | Specifies that filter member value must be less than value provided in operation argument. Operation with this operator expects single _operation argument_. | | `lte` | Less than or equal to | Specifies that filter member value must be less than or equal to value provided in operation argument. Operation with this operator expects single argument. |
Custom operator
The filter may support custom operator - an operator with custom name (and behavior).
Example: If filter named "Foo" supports the custom operator named "op", accepting "bar" as an operation argument, example query would look like this:
Foo=op:bar.
Default operator
The filter syntax allows not to specify the operator explicitly. If no operator is explicitly specified in the URI, default operator is used. Each filter may have different default operator. If not stated otherwise, the default operator is eq.
Example: With assumption that
eqoperator is default operator for "DiscountRate" filter, both following queries are equal:
DiscountRate=eq:10
DiscountRate=10
Example: If filter named "Foo" has the custom operation "op" marked as default, you can specify the query from example above without explicitly stating the operator, like this:
Foo=bar.
Collection operation arguments
Some operators, such as in and nin are paired with argument that is an collection. To delimit these values within operation argument, comma character (,) is used.
Example: Filter named Month with one operation, that has in operator and one argument that is an collection of three string values: "January", "February" and "March".
Operation argument escaping
Operation argument must be encapsulated in double quotation marks (") if their string representation contains at least one of following special characters:
,(conflict with collection operation argument separator):(conflict with operation segments separator);(conflict with operations separator)
If argument is an collection, each value is escaped separately:
If argument contains double quotation mark character ", this character must be escaped with backslash \. Example: Filter named "Actor" associated with operation with eq operator and string value Dwayne "The Rock" Johnson:
Last updated