Handling Special Characters in URLs With WSO2 ESB

Let’s say you have a URL which needs to send an email address as a query parameter. If you create a standard REST API within WSO2 ESB (or EI) and try to match the query parameter in a uri-template, it will fail during execution. As an example, if you have the below API definition.

<api xmlns="http://ws.apache.org/ns/synapse" name="EmailAPI" context="/voice">
   <resource methods="POST GET" uri-template="/details?email={email}">
      <inSequence>
         <log level="full">
            <property name="EMAIL" expression="$url:email"/>
         </log>
         <respond/>
      </inSequence>
   </resource>
   <resource methods="POST GET" uri-template="/phone/{number}">
      <inSequence>
         <log level="full">
            <property name="PHONE" expression="$ctx:uri.var.number"/>
         </log>
         <respond/>
      </inSequence>
   </resource>
</api>

You would expect that following request to work properly.

http://localhost:8280/voice/details?email=chanaka@gmail.com

If you hit the above URL, you will get a “404 not found” error. The reason is ESB cannot dispatch the request to a matching resource since you have special character “@” in the URL path. You can find more information about these special characters here.

In this post, I’m going to explain how you can resolve this special character issue using two approaches.

Solution 1

The first solution is to URL encode the special character when sending the request to this API. Now the request URL should look like below.

http://localhost:8280/voice/details?email=chanaka%40gmail.com

When you send the request with the above URL, it will dispatch to the correct resource and you will see the log message with the proper email address similar to the below log entry.

[2018-05-04 13:35:12,660] [EI-Core] INFO - LogMediator To: /voice/details?email=chanaka%40gmail.com, MessageID: urn:uuid:281dcd97-2043-45a3-8842-d3a0b27f5efa, Direction: request, EMAIL = chanaka@gmail.com, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><name>chanaka</name></soapenv:Body></soapenv:Envelope>

Even though the incoming URL parameter is encoded, once it is accessed within the mediation sequence using the $url syntax, it is giving the properly decoded value.

This solution is easier for the developers, but harder for the users, of this API.

Solution 2

Instead of asking your users to change the client side implementation, we can handle this within the ESB itself using a simple trick. The trick is to use "*" to define the URL path when creating the API. You can create an API similar to the below configuration.

<api xmlns="http://ws.apache.org/ns/synapse" name="AsterixAPI" context="/voice">
   <resource methods="POST GET" uri-template="/details*">
      <inSequence>
         <log level="full">
            <property name="EMAIL" expression="$url:email"/>
            <property name="PHONE" expression="$url:phone"/>
         </log>
         <respond/>
      </inSequence>
   </resource>
   <resource methods="POST GET" uri-template="/phone*">
      <inSequence>
         <log level="full">
            <property name="PHONE" expression="$url:phone"/>
         </log>
         <respond/>
      </inSequence>
   </resource>
</api>

Here we have defined the matching uri-template with "*" so that it will capture all the requests coming into this context "/voice/details*". Now, what happens if you send a request to the following URL?

http://localhost:8280/voice/details?email=chanaka@wso2.com&phone=(077)-3337238

In this URL, we have 3 special characters, @, (, ), but we are not asking the client to URL encode those parameters. Rather, the user can send them as it is to the API and within the ESB mediation runtime, these query parameters are accessed using the $url syntax. Here we are specifically ignoring these special characters from template matching to avoid the special character impact. Now you can see a log similar to what I've got below if you send a request to the above URL.

[2018-05-04 14:20:57,841] [EI-Core] INFO - LogMediator To: /test2/email?email=chanaka@gmail.com&phone=(077)-3337238, MessageID: urn:uuid:6926aa13-8f1d-40ef-afb9-02021d2d908a, Direction: request, EMAIL = chanaka@gmail.com, PHONE = (077)-3337238, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><email>chanaka@gmail.com</email></soapenv:Body></soapenv:Envelope>

In the above log, you can clearly see that email address and phone number query parameters are accessed within the mediation sequence in the proper format.

These are the two solutions for the URL special character related requirements within WSO2 ESB or EI.