FilterQueryString

Category: Modules
Subcategory: All

Overview

Add dynamic filtering to your REST API endpoints. What if you would like to get all orders with an order value between 150 and 200? Query entities by filter parameter: /orders?filter=orderValue gt 150 and orderValue lt 200! In addition, sorting is supported: /orders?orderBy=paymentStatus asc,price desc

Documentation

https://youtu.be/02YKjcNjLdU
Demo urlhttps://filterquerystringp-sandbox.mxapps.io/rest/myservice/v1/testentities?orderBy=active,price%20desc&filter=price%20lt%2050%20and%20precision%20le%200.05

Description

This module parses both filter and sorting query string parameters, which allows advanced filtering and sorting in your REST API endpoints. Syntax of query string parameters correspond to the Microsoft API Guidelines as most API guidelines do not specify the syntax of these parameters.

Typical usage scenario

Expose a resource (entity) using the REST publish functionality and give the consumer of the API the possibility to apply filtering and sorting based on the use cases. This prevents re-work in terms of adding new query string parameters every time new attributes are added to the filter functionality.

Features and limitations

Not all operators are supported yet. Grouping and OR operators are not yet implemented. The following operators are supported by the filter query string parameter:

OperatorDescription
Comparison operators 
eqEqual
neNot equal
gtGreater than
geGreater than or equal
ltLess than
leLess than or equal
Logical operators 
andLogical and


Dependencies

Installation

Add the module to your project. No additional installation required. Use the actions/microflows in the USE_ME folder.

Configuration

  • Configure a REST Publish endpoint that exposes a collection (e.g. GET orders or GET customers).
  • Add a filter and sorting query string parameter to the endpoint (e.g. filter and orderBy) and map those to the microflow parameters. The filter query string parameter should be in the format filter=description ne ‘test’ and price gt 100 and price lt 200. The sort query string parameter should be in the form orderBy=price desc,description asc or orderBy=id (ascending by default). The syntax is defined in the Microsoft API Guidelines.
  • Create a list of FieldNameMapping objects only if field names in your API deviate from the field names in your entity (e.g. orderId to OrderId). By specification of the mapping, the module knows when filtering on a specific field, which attribute to filter on in your database.
  • Use the IVK_ParseSortString microflow to translate your sort query string parameter into Sort objects. Apply the same field name mapping if required (use the IVK_MapFieldNamesForSortList).
  • Use the ParseFilterQueryString action to translate your query string into an XPath query. Don’t forget to apply exception handling in case the filter query string parameter is invalid. Look into the example IVK_GetOrders to see how exception handling is applied.
  • Use the RetrieveObjects or RetrieveObjectCount to get your objects based on the XPath generated in the previous step. Don’t forget to apply exception handling.

Releases

Version: 1.0.0
Framework Version: 8.1.0
Release Notes: Initial version.