Introducing filter parameters for API flows in IBM App Connect

In the latest update to IBM App Connect, you can specify API query parameters that filter the behavior of App Connect API flows.

For example, with the following API query parameters ...?firstname=Fred&company=Abc you can use a Retrieve Customer with filter operation to retrieve only (that is, filter) the customer records that match the values of those parameters.

When called an API with the query parameters, the API responds with an array of customer records, such as:

[
    {
        "firstname": "Fred",
        "lastname": "Jones",
        "company": "Abc",
        "email": "fred.jones@abc.com"
    },
    {
        "firstname": "Fred",
        "lastname": "Smith",
        "company": "Abc",
        "email": "fred.smith@abc.com"
    }
]

In App Connect flows for APIs, you can configure parameters to filter the behavior of the following operations of API flows:

• Retrieve with filter
• Update or create with filter

When you create an API flow to use either of these operations, you can exploit the following features:

1. Select fields from the API model for use as filters
2. Use the selected filter fields when you implement flows and map actions and the API response
3. When calling the API, specify values for the filter fields as API query parameters

Let’s work through a simple flow design, which demonstrates these features.

Scenario

An API Developer wants to enable API consumers to retrieve customer records where the values for firstname and company fields match values that a consumer provides as API query parameters. In this example, the App Connect flow for the API is used to retrieve Leads from an IBM Db2 database.

In App Connect we first create flows for an API with the model name Customer, then define properties that make up the model; in this case, firstname, lastname, company, and id (used as the model’s ID field).

We then define a Retrieve Customer with filter operation on the Customer model, select filter fields, and then implement a flow, in which we add an IBM Db2 Retrieve Leads action and map the filter fields to Db2 Lead fields.

The list of filter properties shows all fields except the model’s ID field. By default, all the fields shown are selected for use as filter fields. Each selected field has a blue edge, and the total number of filter fields is shown. If you do not want a field to be used as a filter, you can click the field which turns its edge grey and decrements the total number of filter fields. For example, we click lastname to prevent it being used as a filter field, which changes the list of filter properties and total as shown in the next figure:

When you edit the flow, example query formats are shown for the Request node:

After the Request node, we add an IBM Db2 Retrieve LEADS records node. On that node, we add conditions for the filter fields (firstname and company); only those filter fields can be selected as shown in the following figure:

On the Response node, we set the Responses field to the type of record that we are retrieving, in this case Leads from the IBM Db2 node. (Note that the response of the Retrieve Customer with filter operation is an array.)

We then map the response fields, selecting from the parent mapping item: Leads, as shown in the following figure. (Note that although lastname and id are not filter fields, we can map their values from the Leads parent.)

When the implementation is complete, the Response body shows all the mapped fields for the model:

Now that we have the implementation is complete, we start the flow and then call the API with filter query parameters. (The filter fields, firstname and company, must be specified in one of the formats shown on the Request node.)

This example showed the use of filter fields for “Retrieve with filter”; the same steps can be used for “Update or create with filter”, but in that case the response is an object instead of an array.

Reference:
Loopback filters format: https://loopback.io/doc/en/lb3/Where-filter.html