Each method that returns lists and collections of resources can be paginated by adding to the URL the following query string parameters.
Filtering and sorting are supported in API v1.1 by using the following query string parameters:
Both parameters must be URL encoded due to the possible presence of reserved characters in the query strings.
Please contact us if you need a custom feature that might be implemented according to your specifications and needs.
|
Resource filtering is done thanks to a dedicated expression evaluator which is capable of transforming the user-provided filter expression into the appropriate SQL statements to query the server database.
This transformation is achieved in two steps:
Usually, resource properties can be accessed through dot notation (ex. message.id) but in some cases, when the property represents a list or an array of sub items (ex. console recipient custom fields) square bracket notation can be used (ex. recipient.Fields['name']).
In case a property is not defined on the requested resource, a suitable error message is returned describing the issue.
There are two supported operators' types :
Mathematical / Logical operators define the relation against two resource properties or between a property and a static value (ex resource.Name == 'David').
TypeRegistry operators define a specific resource property characteristic (ex. resource.Email.Contains('mailup.com')).
Supported mathematical and logical operators are:
TypeRegistry operators are all the type methods and properties as defined by the C# language code definition. For details on method names please refer to MSDN online documentation.
Supported type are:
All the supported operators can be mix-matched to fulfill the user's needs.
As far as some value casts and definitions can be done through RegistryType operators, direct casting and particular type definition (ex. a DateTime value) can be inferred directly using a specific syntax definition.
In particular:
Request for subscribed list recipient whose email address contains 'mailup.com' sorted by 'name' descending (custom fields)
Method | URI | Filter expression | Sorting expression |
---|---|---|---|
GET | /Console/List/{ID_LIST}/Recipients/Subscribed | Email.Contains('mailup.com') | Fields['FirstName'] desc |
Resulting URI | /Console/List/1/Recipients/Subscribed?filterby="Email.Contains(%27mailup.com%27)"&orderby="Fields%5b%27FirstName%27%5d+desc" |
Request for subscribed list recipient whose first name is 'Davide' sorted by 'Email' descending
Method | URI | Filter expression | Sorting expression |
---|---|---|---|
GET | /Console/List/{ID_LIST}/Recipients/Subscribed | Fields['FirstName'] == 'Davide' | Email desc |
Resulting URI | /Console/List/1/Recipients/Subscribed?filterby="Fields%5b%27FirstName%27%5d+%3d%3d+%27Davide%27"&orderby="Email+desc" |
Request statistics for message views done by recipients whose email contains mailup ordered by view count descending
Method | URI | Filter expression | Sorting expression |
---|---|---|---|
GET | Message/{id_Message}/List/Views | Email.Contains('mailup') | Count desc |
Resulting URI | /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)"&orderby="Count+desc" |
Request statistics for message views done by recipients whose email contains mailup, between 2013/01/01 and 2013/01/31 ordered by view count descending
Method | URI | Filter expression | Sorting expression |
---|---|---|---|
GET | Message/{id_Message}/List/Views | Email.Contains('mailup') && [Date >= #2013/01/01# && Date < #2013/01/31#] | Count desc |
Resulting URI | /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+%5bDate+%3e%3d+%232013%2f01%2f01%23+%26%26+Date+%3c+%232013%2f01%2f31%23%5d"&orderby="Count+desc" |
Request statistics for message views done by recipients whose email contains mailup, in the last 24 hours ordered by view count descending
Method | URI | Filter expression | Sorting expression |
---|---|---|---|
GET | Message/{id_Message}/List/Views | Email.Contains('mailup') && Date >= DateTime.Now().AddDays(-1) | Count desc |
Resulting URI | /Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+Date+%3e%3d+DateTime.Now().AddDays(-1)"&orderby="Count+desc" |
Sorting queries define how results should be ordered. Sorting properties are all first-level properties as defined in resource service contracts and only in particular cases (ex. recipient custom fields) second-level ones can be used.
A sorting query is represented by a string of properties and operands divided by a colon (',') and semicolon (';'). Properties that share the same sorting direction can be listed as comma-separated values (ex. name, surname desc). When a different sorting direction has to be specified, the new property list must be separated by the others with a semicolon (ex. name, surname desc; email asc).
The way the sorting query is written, determine also the priority of sorting execution, so in the case of "name desc; email asc" the results are initially ordered by name descending and then by email ascending.