In a previous post, we discussed integrating APIs with application/x-www-form-urlencoded payload.  In this post we will discuss integration of a POST API that has the multipart/form-data format.  Multipart/Form-Data is a popular format for REST APIs, since it can represent each key-value pair as a “part” with its own content type and disposition.  Each part is separated by a specific boundary string, and we don’t explicitly need Percent Encoding for their values. 

Multipart/Form-Data payloads are especially popular in File Upload scenarios because the file can simply be represented by its own mime type. We will demonstrate multipart/form-data POST API integration with Visual Builder using the freely available https://postman-echo.com/post  API which accepts multipart/form-data format and returns the same input as a response.  A point to note is that multipart/form-data type requests are not testable in the Design time using the test tab (like we did for application/x-www-form-urlencoded payload).  However we can still configure the service connection and test it from within an application that calls this API.

As before we divide the whole integration into 3 tasks:

  1. Defining the Service Connection 
  2. Creating a simple form with a file input and an input text element
  3. Passing the file input and the input text element to the Service Connection 

Create the Service Connection

The Postman Echo service is designed to accept arbitrary inputs, however we will pass the following individual parts :
name : String
myFile : a File

Create the Service Connection using the "Define by Endpoint" flow

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

     

In the Authentication tab,

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

Next in the Request tab,

  • Media Type – change the default application/json to multipart/form-data using the pencil icon .  The Body part will be greyed out as in the previous example.

In the Response tab,

  • Supply an example response here like one below (it is not possible to Test the Service in this case).  The Media type for the response in our case continues to remain application/json; you can change it as per your service.  If you dont want to use the response in any way in your application, you can supply an empty json ( {} )as well.

{
    "args": {},
    "data": {},
    "files": {
        "filename": "XXX"
    },
    "form": {
        "name": "hello"
    },
    "json": null,
    "url": "https://postman-echo.com/post"
}

  • Now click on “Create” to create the Service Connection

This completes the definition of a Service Connection.  Let us now create a simple web application which will accept the a file and some other parameters and pass them to the Service as individual “parts”

Create a form to gather data

  • Create a web application.  Mine is called multiparttest
  • Add an input text element by dragging it from the Component palette.  This will store the "name" attribute of our REST API payload
  • Let us add a file picker in order to select a file from the local computer.  You will need to add the file picker component to the page imports, since this is not available in the standard components in the Component Palette.  More on the Oracle JET filepicker component here.

  • Next, toggle the VB page designer to the ‘Code’ mode.  Below the input text, add the following code which will add the filepicker:

<div class="oj-flex">
    <oj-file-picker id="oj-file-picker-1902456664-1" class="oj-sm-flex-1" accept="[[[ 'image/*']]]" selection-mode="single"></oj-file-picker>
</div>

  • Toggle back to ‘Design’ mode.  Create a page variable called ‘inputName’ of type String.  Bind this variable to the input Text element in our page.

 

 

Create an action chain for the FilePicker

Next we add the Action chain which will run when we select the input file and pass the form data to the /post endpoint

  • Select the filepicker and navigate to “Events”.  Select the Custom event option and choose “ojSelect” event, which occurs after we select the file from the picker. 

  • On the "ojSelect" event, add a Page Action Chain called “FilePickerSelectChain” to handle this event.  The basic structure of the Action Chain is as follows:

The elements of the Action chain are described below

  • Call Rest Endpoint – Attach the Service Connection POST endpoint.  There are two things that need to be populated here (other things being optional)

Content Type : multipart/form-data
Body : (Static Content) 
{
 "myFile": "{{$chain.variables.detail.files[0]}}",
 "name": "{{$page.variables.inputName}}"
}

Though the payload that is supplied looks like JSON, the VB runtime is designed to convert all the attributes in the JSON payload as individual parts of the multipart request with appropriate mime types.  So in our example both the attributes myFile and name would be the two parts of the multipart message


 

  • Success – Fire Notification

  • Failure – Fire Notification

 

Now it’s time to run our application.  Remember we have configured our REST API to be triggered when a file is selected from the FilePicker.  You can trigger the API on click of a button as well.

A quick inspection of Chrome Developer Tools reveals the Content type ( multipart/form-data) as well as the FormData elements