How to Build a Proxy Server for REST Requests to a SOAP API
Working with legacy code provides unique challenges to software engineers. Many engineers prefer working on greenfield projects, as there are fewer constraints than with existing work. With legacy projects, you must work within a language and framework while adhering to existing code conventions and patterns. All the decisions made before you begin work can quickly bind up your development.
Some development is a mix of old systems with new applications. That was the case for a recent project I took on. For that project, I built a modern front-end client to talk to a legacy SOAP API. This front-end was not writing to the API, only reading data. SOAP requires a lot of data formatting to adhere to request standards, and I wanted to keep the front-end app as lightweight as possible. To do this, I created a proxy server to translate REST requests from the front end into SOAP requests to the legacy SOAP API.
What is an API?
Before we can build a proxy server, or even discuss SOAP vs. REST APIs, we first need to define APIs. What is an API? An API, or application program interface, is code between two applications that allows them to communicate.
The most common API you interact with today is a social media app. A phone app is a client retrieving and displaying posts or content to the user. Social media companies have massive databases with the content that the user wishes to post to and read from.
For your app to talk to the databases, they must have a mutual language. Your client speaks JavaScript, but the databases speak some version of SQL. Here is where APIs come in.
An API receives requests from a client or application, reads the request, performs an action against the server or receiving app, and returns a response.
These actions could be creating a new Instagram post, requesting the status of your Amazon order, or streaming your favorite Netflix show. The takeaway is an API consists of a software program that fulfills this request and response cycle.
What are the Differences between REST and SOAP APIs?
Today, REST(ful) APIS dominate the software world. The REST API is built on structured data as resources acted on with many actions (POST / GET / PUT …) located by resource identifiers (URIs or uniform resource identifiers).
REST is built on the style of requests and responses and does not care as much about the data format. REST is incredibly flexible as it can return data in JSON, HTML, XML, and plain text formats. As long as you adhere to the request/response style and HTTP protocol, it will work.
SOAP is more rigid as it was designed to be repeatable, secure, and language and environment-agnostic. Where REST is a style, SOAP is a structure for handling requests and responses. With SOAP there is only one data format for requests and responses: XML. Requests consist of XML envelopes, or special required XML structures for requests.
While SOAP has many benefits including being secure, coding language and transport protocol independent, and transparent in errors, its rigidity has led to it falling out of favor with some developers.
The benefit of SOAP is a robust, uniform data structure. This uniformity is also a drawback, as the data is bloated and requires processing to convert data to a usable JavaScript structure. SOAP also does not support caching, leading to unnecessary calls to the server.
I wanted my calls to be lightweight and cacheable, so I decided the best solution was for our client to call a lightweight and cacheable REST API. This REST API could form the calls and decide whether to make the call to the SOAP API or use cached data.
What is a Proxy Server?
The simplest form of communication comes between two parties. Examples of simple communication include asking your neighbor what day to put out your trash. Or it could be your computer querying a website for the best savory empanada recipe. For basic actions, having fewer pieces makes everything smoother.
Sometimes, your actions are not basic and require another party to complete your needs. Here, we introduce a third-party, or proxy server to help complete our requests.
There are many types of proxy servers and reasons to use them. You have likely used a forward proxy server if you use a VPN while surfing the internet. VPNs are a special proxy server that intercepts requests from a client device and encrypts the data before sending the request to the intended server:
Encrypted forward proxy servers are great for user privacy as they mask the actual origin of a request and encrypt the sent data. Another commonly used proxy server is the reverse proxy server. This server sits between a target service and a client and performs several actions including load balancing, security from attacks, and SSL decryption/encryption.
For our example, we will be using a forward proxy server architecture. Our client wants specific resources from our legacy server. However, the client does not speak the same language as our target SOAP API. The proxy server will receive the message from our client as a REST request, translate it to a SOAP request, and then return a parsed REST response.
How do We Build a Proxy Server for Using REST requests on a SOAP API?
We have discussed APIs, the difference between REST and SOAP APIs, and what a proxy server is. We are now ready to describe the architecture of our solution.
Without a proxy server, our app architecture looks like this:
Our client SPA makes requests for data from our SOAP server. This would work, but we have two issues with this design. First, our client is doing a lot of lifting with creating XML envelopes, formatting the POST request, and making sense of the SOAP response.
The second issue is SOAP does not allow for caching, meaning that we will make many unnecessary calls to our SOAP API for data that has not changed. The data will be updated daily meaning we do not need to fetch real-time updates.
To address these problems we can add a proxy server to our architecture:
We add a REST API between our client and SOAP API. This offers several benefits. First, our client can communicate with our servers in lightweight REST calls and receive lightweight JSON objects for populating the UI.
Second, our caching layer on our proxy server will allow for lightning-fast responses to our client requests. We will discuss cache invalidations more later, but hopefully, we will only have one long call per day for data on each of our resources.
With caching, our calls will be much faster than talking directly to the SOAP API. REST can read our request and check a cache to see if the result has been fetched that day. We do not expect our data to become stale sooner than every 24 hours. Therefore, we can set a cache policy that we only make the call to SOAP every 24 hours. We do not need a SOAP call to complete the request if our cache has not expired.
We have talked about the architecture and benefits of using a REST proxy, but how are we translating our REST data to SOAP and back again? We are getting a URI with some parameters and turning this data into an XML structure that adheres to SOAP envelope requirements. We then have to turn this SOAP envelope into a JSON object for our UI.
Here is a diagram of the journey of data from UI request to UI display:
We send a request to our REST API with a URI. Our request is routed to the appropriate controller using the information in the URI to populate the XML body for our XML envelope. We then POST a request to our SOAP API for the appropriate data.
The SOAP API will return an XML envelope. Now, our coding is fun again. How do we turn a SOAP XML response into a JSON response for our client? The best solution for this project was to use the xml-js npm package. This package allows you to parse XML and return a JSON string.
There are some considerations for using this package, specifically the xml2json method. This method takes an options hash that contains keys like a “compact” key. XML is hard to use in the UI because it is complex with a deeply nested object structure. This compact key is a boolean value that determines whether we get a simpler version of the XML in our JSON or the original. Here are example outputs for compact and non-compact JSON from the docs:
As I said, we get a JSON string, so we still need to parse the value to get a JSON object. We have a JSON object to serialize with certain values and a specific shape.
Final Thoughts
One of the most beautiful parts of programming is its flexibility and freedom. Even though legacy code offers constraints on direct code applications, developers can build whatever they need to solve a problem. Building a proxy server allows for lightweight and cacheable calls between our UI app and the legacy SOAP API. If you have to put some work into a solution, always look for an elegant and functional way forward.
