Comment on page
NData query syntax
This section describes the query syntax used in PORTOS API, called "NData".
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
Value of each filter is semicolon-separated (
;) list of operations.
Each operation consists of segments delimited by colon (
:) character. First segment is an operator, followed by 0 or more operation arguments.
Example: Filter member named "DiscountRate" is associated with single operation, that has "gt" operator and one operation argument, value 10. Result query is:
Multiple occurrence of same filter member is supported, thus both following queries are equal:
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:
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
Example: With assumption that
eqoperator is default operator for "DiscountRate" filter, both following queries are equal:
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:
Some operators, such as
ninare paired with argument that is an collection. To delimit these values within operation argument, comma character (
,) is used.
Example: Filter named
Monthwith one operation, that has
inoperator and one argument that is an collection of three string values: "
February" and "
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
eqoperator and string value
Dwayne "The Rock" Johnson:
Actor=eq:"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: