Co-author - Shefali Vaish
IBM App Connect provides connectivity to 100+ smart connectors where users can connect to a variety of applications with ease, without needing to understand the complexities of the endpoint. It also supports several technology-based connectors such as HTTP and SOAP which can come to your rescue in the absence of a first-class connector. However, there is catch that these generic connectors cannot understand the schema for the endpoint you are trying to invoke.
For example, consider invoking a legacy system or any external system which exposes REST endpoints, and has a huge complex schema as input which we want to invoke via an HTTP connector.
Ideally, we would develop an API or event flow where we have the HTTP node as one of the actions. Before we invoke the endpoint via the HTTP node, we need to prepare the required input structure using flow constructs such as 'set variable' which is time consuming.
In this article we will demonstrate how we can inject the complex schema into the flow document.
Let’s start by creating an API flow with a custom GET operation where the API user wants to connect to a complex endpoint using the HTTP node. Here we are using the complex schema from the Geo map endpoint.
For reference: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics-api/code-discover-place.html
Image 1. API flow with operation getPlaces added
To generate the schema, we will use the sample payload from the endpoint and use a JSON Parser node to generate the complex schema.
Paste the sample payload JSON in the Example JSON section and click on the Generate Schema button. This will generate the JSON Schema for the complex schema given from the complex endpoint.
Image 2. Generate JSON schema using JSON parser node
Copy the generated JSON Schema, you can use any utility that converts JSON to YAML, there are many free online tools available for this. e.g https://onlineyamltools.com/convert-json-to-yaml. After converting, copy the properties section (highlighted) from the converted YAML in the image below.
Image 3. Convert JSON to YAML
We can now delete the JSON Parser, as it was only required to get the schema in one-click. If you already have the schema, this step can be skipped.
Now add the Set variable node and add the first variable. For example 'first_set_variable'.
Image 4.Use set-variable node
Export your flow as YAML and delete this flow.
Image 5. Export and delete the flow
Open the YAML in any editor and edit the Set variable section. To achieve this, follow the steps below.
- Search for 'set-variable'.
- Replace the properties object with the properties object generated while converting the JSON Schema to YAML (refer to image 3).
Image 6.Edit the imported YAML to add more properties from generated schema
Now save the flow and import it, you can see that the Set variable node has all the complex properties from the schema without manually creating all the variables one by one, you can map as many variables as you want.
Image 7. Set variable node having complex properties
To connect to the Map Geo endpoint, add the HTTP node and map the required properties from the Set variable node.
Image 8. Add HTTP node and complete the mappings from previous nodes
Map the response from the HTTP node to the Response node of the API and start your flow for testing.
Image 9. Complete Response node mappings
The benefits of applying this approach mean that you would not need to add complex schema properties one-by-one using the UI editor, now, designing the flow with a complex property is much faster. Also App Connect validates the flow on import, if you get any errors while importing, ensure that you fix them accordingly and import.