How to Upload Image Files With a WSO2 REST API and VFS

Below, we can see the code of the REST API that we defined on Enterprise Integrator:

<?xml version="1.0" encoding="UTF-8"?>
<api context="/image" name="ImageAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST" uri-template="/add">
        <inSequence>
            <log level="full" />
            <!--
                1. Reading the JSON attributes from the request payload;
            -->
            <property expression="json-eval($.fileName)" name="fileName" scope="default" type="STRING"/>
            <property expression="json-eval($.fileContent)" name="fileContent" scope="default" type="STRING"/>
            <!--
                2. Creating the Payload for a binary payload.
            -->
            <payloadFactory media-type="xml">
                <format>
                    <ns:binary xmlns:ns="http://ws.apache.org/commons/ns/payload">$1</ns:binary>
                </format>
                <args>
                    <arg evaluator="xml" expression="$ctx:fileContent"/>
                </args>
            </payloadFactory>
            <!--
                3. Even using a binary payload, the Axis2 frameworks keeps considering the payload as text.
                We use a script mediator to set the fist node as binary;
            -->
            <script language="js"><![CDATA[var binaryNode =       
      mc.getEnvelope().getBody().getFirstElement().getFirstOMChild();  
   binaryNode.setBinary(true);]]></script>
            <log level="full" >
            <property name="fileName" expression="$ctx:fileName"></property>
            </log>
         <!--
            4. We set the name of the file that will be saved in the disk using a VFS parameter
         -->
         <property name="transport.vfs.ReplyFileName" expression="$ctx:fileName" scope="transport"/>
         <log level="full">
            <property name="fileName" expression="$ctx:fileName"/>
         </log>
         <!--
            5. We need to set the OUT_ONLY property and remove the REST_URL_POSTFIX to make the API to be able to save the file
            and set the expected file name.
         -->
         <property name="OUT_ONLY" value="true"/>
         <property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>
         <!--
            6. We use the call mediator in order to invoke a vfs endpoint with the target directory.
         -->
         <property name="messageType" value="application/octet-stream" scope="axis2"/>
         <call>
            <endpoint>
               <address uri="vfs:file:///E:/test/"/>
            </endpoint>
         </call>
         <!--
            7. We define a success message to be the respose of the REST API request.
         -->
         <payloadFactory media-type="json">
            <format>
                {                
                    "status": "success",                
                    "statusMessage" : "Image Uploaded"               
                }            
             </format>
            <args/>
         </payloadFactory>
         <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </resource>
</api>

Let us explain each part of the above code.

We declared a REST API named ImageAPI that is responding to the context /image. This API has only one resource, /add, that will respond to POST requests.

Our API expects a payload like below:

{
  "fileName":"imageNew2.png",
  "fileContent": "Base64 IMAGECONTENT"
}

We send the file name and the image content to the API, Base64 encoded.

1. Reading the JSON Payload Content

The first step is to read the JSON payload properties using the property mediator and JSONPath using the json-eval method.

<property expression="json-eval($.fileName)" name="fileName" scope="default" type="STRING"/>
<property expression="json-eval($.fileContent)" name="fileContent" scope="default" type="STRING"/>

2. Build the Payload to Save the Image to Disk

We use the payloadFactory mediator to build a binary payload. Using the fileContent property defined in the step above as parameter:

<payloadFactory media-type="xml">
    <format>
        <ns:binary xmlns:ns="http://ws.apache.org/commons/ns/payload">$1</ns:binary>
    </format>
    <args>
        <arg evaluator="xml" expression="$ctx:fileContent"/>
    </args>
</payloadFactory>

3. Set the Binary Property for the Payload Data

Even using the binary payload, the framework still handles it as a text payload. We use a script mediator to set the binary flag to the first node.

<script language="js"><![CDATA[var binaryNode =       
      mc.getEnvelope().getBody().getFirstElement().getFirstOMChild();  
   binaryNode.setBinary(true);]]>
</script>

4. Set the File Name to Be Saved

We defined a VFS parameter to specify the name of the file that will be saved in the Disk.

<property name="transport.vfs.ReplyFileName" expression="$ctx:fileName" scope="transport"/>

5. Set Some Required Properties to Enable the File Saving

We need to set the properties below in order to enable the API to save the file and use the specified file name defined in the previous steps.

<property name="OUT_ONLY" value="true"/>
<property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>

6. Write the Image to the Disk Using VFS Endpoint

We send the payload to the disk as a file using a call mediator with a VFS endpoint, having the target folder as the address.

<call>
   <endpoint>
      <address uri="vfs:file:///E:/test/"/>
   </endpoint>
</call>

7. We Respond With a Success Message to the Client

We use payloadFactory to create a simple response message to the client that made the request.

<payloadFactory media-type="json">
   <format>
       {                
           "status": "success",                
           "statusMessage" : "Image Uploaded"               
       }            
    </format>
   <args/>
</payloadFactory>

Conclusion

Now we are able to use a WSO2 REST API and VFS to upload image files and save them to disk. I hope you enjoyed.

See you in the next post!