The Visual Builder Cloud Service Blog

Consuming REST APIs in VB - application/x-www-form-urlencoded

Aparna Gaonkar
Product Manager

Service Connections in Visual Builder support common payloads for REST APIs like application/json (default), application/x-www-form-urlencoded, multipart/form-data etc.  This series of blog posts will highlight how to integrate APIs with these payloads with Visual Builder.

In this blog post, we will focus on the integration of a REST API that accepts application/x-www-form-urlencoded format.  This media type is less popular these days and is mostly replaced by multipart/form-data, which will be covered in a later post.  The form-urlencoded format can be visualized as a list of percent-encoded name-value pairs separated by the ampersand (&) character (much like the query string format).  

For the purpose of demonstration of the various payloads I will be using the freely available REST client testing server https://postman-echo.com

There are three broad tasks to create a full application that calls a REST API with application/x-www-form-urlencoded format 

  1. Defining the Service Connection 
  2. Creating a simple form with two input text elements bound to a page variable
  3. Passing the page variable to the Service Connection on click of a Button

Each of these tasks are described below (If some of these are new to you, check out the Visual Builder learning path, especially the one on Service Connections)

Define the Service Connection

Create the Service Connection using “Define by Endpoint” flow.  

  • Method = POST
  • URL = https://postman-echo.com/post
  • Action Hint = Create




Next, in the Authentication tab, give the following

  • Enable Authentication/Proxy - checked
  • Authentication = “None” (In a real world case, you will need to select appropriate authentication as per your service needs)



In the Request tab, change the default Media Type (application/json)  to application/x-www-form-urlencoded using the pencil icon .  As soon as you change this, the Body part will be greyed out (but we will still be able to test the Service)


Navigate to the Test tab.  Now, we will generate a sample Response by testing the Service 

  • Request Body – lets have a string of simple key-value pairs as below(if you are using your own data, make sure these are Percent Encoded if they contain non-alphanumeric characters)


  • Click on the Send button.  You should be able to see the example response as below:




  • Click on the “Copy to Response Body” to store this as an example response, and finally click on “Create” to save the Service Connection Created

This completes the definition of a Service Connection which is ready to be used in a Web or Mobile application.

Create the form page

Let us now create a simple web application which will accept the form parameters and pass them to the Service. 

  • Create a web application with a logical name (mine is called “FormUrlEncodedTest”)
  • From the main-start page, create a new Variable called “inputData” of type Object.  Add two fields to it “firstValue” and “secondValue”


  • On the main-start page, add two “Input text” components from the Component palette.  Change their labels to “First Value” and “Second Value” respectively.
  • Click on the first input text, and in the Property inspector, click on Data sub tab.  Click on the "fx" icon to bind the and bind the input text data to "inputData.firstValue"


  • Repeat for the second input text field and bind it to secondValue attribute
  • Finally add a button that will call the REST API and pass the values of both input elements.  Select the button and go to the Events tab and add a new Event.  Use the “ojAction” Quick Start to automatically create an Action chain for the event as well.  


Add the Action Chain

Next we add the Action chain elements.  In the Action chain, first we will prepare the body for the /post REST API using a custom JavaScript function and then call the /post  REST API and fire an appropriate notification if success or failure.  


  • Create a page level function that takes care of Percent Encoding and forming the body of the request from the variable.  A sample function is as follows:

    PageModule.prototype.prepareRestBody = function(details) {
    var formBody = [];
    for (var property in details) {
      var encodedKey = encodeURIComponent(property);
      var encodedValue = encodeURIComponent(details[property]);
      formBody.push(encodedKey + "=" + encodedValue);
    formBody = formBody.join("&");
    return formBody;


  • In the Action chain, use the action “Call Module function” to use prepareRestBody, and we pass the variable we created ("inputData") to the input parameter "details"




  • Next, add the “Call Rest Endpoint action” to the action Chain and select the appropriate endpoint correspond to your API.  In our case it is the /post endpoint


  • We also need to map the body of the REST Action call with whatever was returned from the prepareRestbody module function

  • Finally we add “Fire notification” actions to both the success and the failure nodes of the “Call Rest endpoint”.  For the success notification, we have a Notification type of “info” and we have also added the values retrieved from the response of the REST API to Summary as below:

{{ $chain.results.callRestEndpoint1.body.form.firstValue + chain.results.callRestEndpoint1.body.form.secondValue}}





This completes our web application.  On adding input values and clicking on the button, you should now see a successful response like this:




Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.