MessageMedia provides fully featured REST APIs for messaging. However, there are also legacy SOAP APIs that are used by some customers for messaging services.
Historically SOAP was the go-to messaging protocol for most web services – however, as the internet evolved developers needed a way to quickly build more lightweight web and mobile applications. Thus, the alternative REST API architecture was developed. REST quickly gained popularity and in 2018, most public web services provided REST APIs.
Some enterprise users still frequently choose SOAP for their web services and at MessageMedia we provide the legacy SOAP web services for those who have built their systems around it. We do, however, encourage migration to the REST APIs where possible, for a number of reasons. It’s worth enumerating these reasons, as the decision to migrate is far more complex than just developer popularity.
REST vs. SOAP
We’ve written before on what REST is. While a lot of the newer APIs are built with REST architecture, and it’s definitely a trendy thing, it also has some real benefits. SOAP and REST are two different approaches to building APIs and two different answers to the question of “how to deal with data transmission”. The main difference is that SOAP is a standardised protocol with official specifications, maintained and developed by the World Wide Web Consortium (W3C), while REST is an architectural style. On the other hand, REST architecture is a set of guidelines for creating RESTful web services. Thus, SOAP comes with strict rules, higher complexity, and requires more bandwidth and resources which can lead to slower page load times.
This means that in 2019, SOAP will be used for certain transactions that require high-level complexity such as APIs for financial services, payment gateways, CRM software, identity management, and so on. In some cases, you may need to process stateful operations. Such scenarios include those where you have to make a chain of operations act as one transaction, like bank transfers. REST was created to address the problems of SOAP that arise when trying to send data for use in customer-facing applications, especially in today’s era of web and mobile apps where page load times = revenue. At MessageMedia we’ve opted for the flexibility of REST, as we continue to build out our messaging capabilities.
The business case for REST
In general terms, the upshot of REST is that for the vast majority of cases, using the REST API will mean you’re able to do more, quicker, and with less bandwidth.
REST works better for modern thin clients (like a web browser) so if you are building a cloud app, REST is the preferable type of API for you. It works for all types of networking equipment and with a variety of service types (Java, .NET, PHP, Ruby, static HTTP, etc.). If you are building any kind of cloud app at all, you need the flexibility of REST. Imagine the tech debt of having to maintain your app while being locked into specific infrastructure requirements because of how you’ve set up access to the SOAP API.
By the same token, you want to be as flexible as possible about the type of client you’re able to run your app on in the majority of cases; even if right now your app runs on known infrastructure, this won’t always be the case. Because of REST’s lightweight and flexible implementation, it’s very Infrastructure friendly – network load balancers, firewalls, proxies, etc. are all optimised for RESTful traffic because they are optimised for HTTP/S traffic.
Finally, REST requests are stateless and thus by definition, highly scalable. They’re also much more efficient – SOAP services always return XML, but our REST service returns JSON, which is the de-facto standard, and these JSON payloads are smaller than their XML counterparts. If you include the SOAP envelope overhead in this calculation, then our REST+JSON payloads are dramatically smaller.
Why REST with MessageMedia
Aside from the general business reasons above, in a MessageMedia specific context, we are upfront about advocating for our customers to move to the REST APIs where possible. The first and most obvious reason for this is that the flexibility of creating a REST web service enables us to innovate with our product offering. We’re building out a number of products and features that are only available via the REST API. When using the SOAP API you will, of course, get the benefit of our super high throughput and reliability – but you won’t get further product innovations like Secure Webhooks, or even the optionality of sending MMS, or any of the other exciting things on our product roadmap, such as RCS. These value-add features are often the key to getting the most value out of our products.
The second reason you might want to move across is if you are continuing to develop new interactions with the API, you will want to have access to our continually-improving developer toolkit for the REST APIs. In the developer relations team, we’re undertaking a number of projects this year to build out the developer toolkits. This includes the soon to be released v2 of the SDKs, which will make it easier than ever to get up and running with integration and more code samples.
The most important part of commencing any move is going to be figuring out to what extent you currently use the SOAP API. Depending on how your site is built to interface with the MessageMedia SOAP API, the level of changes required will vary. For example, in a simple use case where a piece of software is using the SOAP API simply to send bulk messages, this will be a relatively simple swap out for a lot of gains in terms of reducing complexity. However, if the software in question is making numerous calls to block and unblock numbers, schedule messages and so on, it will be necessary to match those functions to MessageMedia REST APIs.
The second part of this will be assessing the level of integration. The level of effort required for a full migration will depend largely on how your current code is built. If your current code uses code libraries the changes should be minimal. However, if your current code doesn’t use code libraries, the changes required may be fiddly. Once you’ve assessed these requirements, depending on your current site and future goals, migrating to the REST APIs and freeing yourself from the shackles of supporting SOAP-consuming code, could present an opportunity for you to optimise other parts of your site.
The good news is, you won’t ever run into a situation where the SOAP API does something for you that the REST API can’t. MessageMedia REST APIs have full feature parity across the numerous SOAP APIs that make up the legacy landscape. Speak to our developers on Slack to assess what functionality you currently use and discuss how to transfer over the REST.