🔍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	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

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.

Sorting

Sorting allows to change order of returned 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.

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	asc	This is an default sort direction.
Descending	desc	Alternatively, descending sort direction can be specified as prepended minus (-) character.

Sorting examples

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

Inclusion

Inclusion allows to extend response format.

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.

Inclusion examples

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.

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:50

• DiscountRate=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
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 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.

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".

Month=in:January,February,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)

FilterMember=eq:"argument:with,special;characters"

If argument is an collection, each value is escaped separately:

FilterMember=in:"foo:bar","foo,bar","foo;bar"

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:

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:

Actor=eq:%22Dwayne%2520%255C%2522The%2520Rock%255C%2522%2520Johnson%22