🔍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:
Parameter | Name | Format | Description |
| Skip | integer | Describing number of records to skip from beginning of result collection. |
| Take | integer | Maximum count of items to be returned. |
Pagination examples
Uri query | Description |
| Skip first 10 items and return rest. |
| Return at most 5 items
|
or
| Skip first 10 items and return at most next 5 items. |
Sorting
Sorting allows to change order of returned items.
Parameter | Name | Format | Description |
| 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:
Sort direction | Name | Description |
Ascending |
| This is an default sort direction. |
Descending |
| Alternatively, descending sort direction can be specified as prepended minus ( |
Sorting examples
Uri query | Description |
| Sort by value1, then by value2, then by value3. Directions are defaulted by server. |
or
| 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. |
and
| Multiple occurrence in query is supported, thus both queries are equal. |
and
| Sort descriptors are case insensitive. Both following queries are equal |
Inclusion
Inclusion allows to extend response format.
Parameter | Name | Format | Description |
| 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
Uri query | Description |
| Single key is specified to be included in API response. |
| 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
Operator | Name | Description |
| Equal | This is default operator, if not stated otherwise. Operation with this operator expects single operation argument.
|
| Not equal | Specifies that filter member value must not be equal to provided operation argument. Operation with this operator expects single operation argument.
|
| 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. |
| 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. |
| Greater than | Specifies that filter member value must be greater than value provided in operation argument. Operation with this operator expects single operation argument. |
| 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. |
| Less than | Specifies that filter member value must be less than value provided in operation argument. Operation with this operator expects single operation argument. |
| 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:
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:
Last updated