How to Proxy Legacy SOAP Services to RESTful APIs

Many companies have legacy SOAP services. And there are advantages to the REST architecture. This article will discuss the implications of proxying legacy SOAP services into RESTful APIs.

SOAP is a web service protocol. SOAP uses XML to transfer data, usually via HTTP. Notably, REST is not a protocol but an architecture. REST specifies that interactions should be:

       
• Client-Server
       
• Stateless
       
• Cache-aware
       
• of Uniform interface
       
• Layered

We won’t go into each of these in depth, but suffice it to say, if you’ve implemented your SOAP services to be stateful (i.e. the server remains aware of the client between requests), then you can’t proxy them to be truly RESTful without re-architecting your services not to be aware of the client between requests.

Additionally, RESTful APIs typically use the following HTTP methods:

       
• GET
       
• PUT
       
• POST
       
• DELETE

If those sound like CRUD operations (Create, Read, Update, Delete), it’s because they are. Get is a read, Put is an update, Post is create and Delete is self-explanatory. If your SOAP services primarily do CRUD operations, then they are good candidates for proxying to a REST architecture. If they have a lot of complex business logic behind them, then you’ll need to re-architect before proxying them to RESTful APIs, though sometimes with a little logic in the wrapper, you can at least support a RESTful GET.

‍

‍Size of Response

‍Many legacy SOAP services return very large object graphs. Part of the allure of REST is small, focused APIs that do one thing and do it well. In some cases, you will want to pare down the response to a very terse, focused response based on what your clients need and not more.

‍

‍XML or JSON

‍The SOAP protocol specifies XML as the message format. REST, however, does not specify a message format: choosing it is up to the implementer. (Transmitting binary data is actually perfectly valid in a RESTful architecture.) There are a number of good reasons to choose JSON over XML these days, including:

       
• Client-side JavaScript can work with JSON very easily and efficiently; and
       
• JSON is terser than XML, which is particularly advantageous when working over mobile networks.

Therefore translating your legacy XML to JSON may be a good idea if you want to save bandwidth and shift some processing from your users’ clients to your server. There should be a library available in your chosen language that will help you do this without much difficulty.

‍

‍Making the Wrapper

‍Your RESTful wrapper on your legacy SOAP service is going to need to do a few things:

       
1. Interpret the HTTP method and any data provided by the client
       
2. Call the legacy SOAP service with the appropriate parameters
       
3. Interpret the SOAP response
       
4. Convert the relevant data to JSON (optional)
       
5. Return the message to the client

You will also want to ensure that you return the correct HTTP status based on the result of the operation in question. Generally speaking, “good” results (i.e. successful GETs, PUTs, POSTs, and DELETEs) should result in HTTP 200 or 204 responses, whereas “not found” errors (i.e. a GET or DELETE of a nonexistent object) should return HTTP 404.

Wrapping your legacy SOAP services as RESTful APIs can open up new possibilities for mobile apps and mobile-friendly web pages. It can give your development team more flexibility and improve time to market. Hopefully this tutorial has given you some ideas for things to consider and keep in mind as you wrap SOAP services with RESTful APIs.