In modern software development, APIs are everywhere. API stands for application programming interface and in practice is a way for one piece of software to communicate with another piece of software. For example, if you want to automatically inject cat facts into your website, you might make a request to the Cat Facts API when a user logs in. Because the Cat Facts API specifies an interface through which it can receive requests, any other software can make these requests automatically and get a response.
API-based communication between software enables greater systems integration, reduces the need for manual human intervention and generally makes for better software. When it comes to the actual implementation of an API, there are two common patterns: SOAP and REST.
In this article, we’ll take a look at when you might want to use one of these patterns versus the other so you can be more informed when developing your next API.
Understanding SOAP APIs
As it relates to API development, SOAP stands for Simple Object Access Protocol and is a protocol for communicating with backend resources using XML. It’s an established protocol that’s traditionally used in enterprise environments, having been originally invented at Microsoft in 1998. SOAP APIs originally became popular in enterprise environments due to their implementation and specific features that made it a good fit for those types of applications.
Advantages of SOAP APIs
- Protocol and messaging format: SOAP API calls are the passing back and forth of XML documents, which both provide the structure for how data is exchanged, but also allow for SOAP API calls to be made across protocols other than HTTP. This means that if two resources aren’t directly connected, XML documents can still be passed via FTP or SMTP and data can be transmitted. SOAP follows a strict and well-defined specification, which makes integration between SOAP-aware systems easier because they can know what to expect from the system they are integrating with.
- Security: SOAP supports a security-conscious approach to API development, supporting encryption, signatures and authentication by default. As a protocol that’s frequently used in enterprise environments, having these security features implemented by default means that SOAP APIs can be integrated into even the highest-security environments.
- Legacy compatibility: Because SOAP relies heavily on XML, which most programming languages support natively, interfacing with a SOAP API can work in most any environment, whether you’re working with the latest and greatest programming language or something a bit more established.
Disadvantages of SOAP APIs
- Complexity: Because SOAP APIs use XML files with typically-extensive metadata to communicate, API requests are both more verbose than REST API requests while also requiring more parsing logic on the receiving end. This means that SOAP requests are more complicated to create in terms of structure and can be more difficult for developers interacting with the request on either side to understand.
- Browser support: SOAP APIs are designed for server-to-server communication, which means that for Javascript web apps or anything that uses client-side, browser-based communication heavily, SOAP isn’t a great fit. While additional tooling and libraries exist for allowing SOAP communication in these types of environments, support for these are not built-in and can be difficult to get fully integrated.
- Performance: The complex nature of SOAP APIs and the fact that XML files are being passed means SOAP APIs are more difficult to cache than REST API endpoints. This means that the performance optimizations that can be made in a REST API context don’t directly translate to a SOAP context. In addition, because the payload with SOAP endpoints are entire XML files, server load can be higher to receive and parse these files as opposed to the more lightweight JSON that REST APIs typically use.
When considering a SOAP API implementation, it’s important to consider these advantages and disadvantages together and understand how they map to your specific use case.
| Advantages | Disadvantages |
|---|---|
| Protocol and format: SOAP APIs have a structured, well-documented message passing protocol and support transport methods other than HTTP. | Complexity: XML-based structure means more verbose requests that are challenging for developers to create and understand compared to REST API requests. |
| Security: SOAP inherently supports strong security measures such as encryption, signatures, and authentication. | Browser support: SOAP APIs don’t support client-side communication natively, which makes it more difficult to support Javascript web applications, for example. |
| Legacy compatibility: SOAP's reliance on XML means it’s supported natively in many environments and programming languages. | Performance: SOAP has caching and performance challenges compared to REST APIs, which use lightweight JSON payloads. |
Understanding REST APIs
In contrast to SOAP APIs which are implemented as a strict protocol, REST (representational state transfer) APIs follow the suggested principles of the REST architecture. While this does allow for a bit more flexibility, it also means that every service that implements a REST API can manage that implementation slightly differently.
Advantages of REST APIs
- Statelessness: By default, REST requests are stateless, which means that all the information needed to take action based on a request needs to be contained in the request itself, independent of any previous request. In addition to being simpler to understand, this means REST resources can be more easily scaled horizontally, without having to keep track of the state of previous requests across different resources.
- Browser support: REST APIs typically communicate via JSON, which is widely supported amongst client-side web application frameworks. In addition, because REST API calls are made to specific URL paths, they can be accessed both by server-side resources (similar to SOAP) but also by any client-side resource that can access a URL.
- Performance: REST APIs are heavily URL-driven, which means that at least read-only requests can be cached like any other web resource. In addition, REST API endpoints usually take JSON as an input, which is more lightweight than the XML files typical in SOAP API requests. This means that REST API requests produce less server load and are generally more efficient.
Disadvantages of REST APIs
- Less formal specification: The downside to the flexibility of REST is that, since there is no formal specification, actual implementations can differ. This lack of universal interoperability means each API integration tends to be a bit more custom, which requires more development time.
- Less built-in functionality: Especially when contrasted with SOAP APIs, REST implementations generally don’t include provisions for security, transaction management (for API calls that write data) or many of the other features that are supported natively with a SOAP implementation. While this “blank slate” can be beneficial in some scenarios, it does mean that more development time may be required depending on how many of these additional features you need.
- Lack of discoverability: As a consequence of a REST APIs flexibility, there is no standardized mechanism for discovering which endpoints are available as part of a given implementation. An API’s documentation can be helpful in this regard, but documentation usually isn’t able to be parsed automatically by a client attempting to interact with the API. Standards have developed around how to communicate the availability of endpoints, but like we discussed above, these must be implemented separately as needed.
| Advantages | Disadvantages |
|---|---|
| Statelessness: All information needed to take action based on a request needs to be contained in the request itself, making each request independent. | Less formal specification: Every implementation can be different because there’s no formal specification. |
| Browser support: REST APIs can easily be called and consumed from client-side applications. | Less built-in functionality: No security, transaction management or other sometimes-required features out of the box. |
| Performance: Because they are URL driven, REST responses can be cached more easily in many cases. | Lack of discoverability: No standard mechanism for discovering which endpoints are available. |
How to choose between SOAP and REST
Choosing between SOAP and REST really comes down to the needs of the consumers of your API. If those using your API are in a legacy or enterprise environment, communicate mostly from one server to another or need alternate methods of communication other than accessing a URL, SOAP would be a great fit.
On the other hand, if your API is going to be access largely by client-side applications, needs a bit more flexibility, or will mostly be read-only requests that could be cached, utilizing a REST architecture might be the better solution for you.
While both of these approaches have their disadvantages as well, these can be mitigated by going into your next API project armed with the knowledge of these pitfalls.
Airplane as a tool for consuming APIs
Airplane is a developer platform for building UIs and workflows. Using Airplane, you can transform scripts, queries, and APIs into sharable applications.
Airplane makes it easy to connect to REST APIs and send REST requests. With REST Tasks in Airplane, you can use Airplane as an interface to access your newly-created API. And once you’re connected, you can use the data coming from your API to quickly and easily build internal tools, admin panels, dashboards and more!
Get started with a free account today and you’ll have your first tool created in no time. If you are a startup, check out Airplane for Startups, where you may be eligible to earn $10,000 in free credits.
