๐NData query syntax
Last updated
Last updated
This section describes the query syntax used in PORTOS API, called "NData".
NData is custom syntax to perform server-side pagination, sorting, inclusion and filtering, inspired by open stack syntax.
Pagination allows to specify range of items received from the API. Pagination can be implemented using one or both of two query parameters:
Sorting allows to change order of returned items.
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:
Inclusion allows to extend response format.
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
.
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 occurrence of same filter member is supported, thus both following queries are equal:
DiscountRate=gt:0&DiscountRate=lt:50
DiscountRate=gt:0;lt:50
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.
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
.
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
eq
operator 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
.
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 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
:
URI Encoding: If NData query is transfered in URI, URI encoding takes place after all NData syntactic rules being applied. Valid URI value would be:
Parameter
Name
Format
Description
$skip
Skip
integer
Describing number of records to skip from beginning of result collection.
$take
Take
integer
Maximum count of items to be returned.
Uri query
Description
$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.
Parameter
Name
Format
Description
$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.
Sort direction
Name
Description
Ascending
asc
This is an default sort direction.
Descending
desc
Alternatively, descending sort direction can be specified as prepended minus (-
) character.
Uri query
Description
$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
Parameter
Name
Format
Description
$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.
Uri query
Description
$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.
Operator
Name
Description
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.