Update 5/12/2016: Watch Stormpath CTO Les Hazlewood’s presentation on REST + JSON API design best practices.
While the SOAP (Simple Object Access Protocol) has been the dominant approach to web service interfaces for a long time, REST (Representational State Transfer) is quickly winning out and now represents over 70% of public APIs.
REST + JSON is simpler to interact with, particularly for public APIs, but SOAP is still used and loved for specific use cases. REST and SOAP have important, frequently overlooked differences, so when building a new web service, do you know which approach is right for your use case?
Spoiler Alert: USE REST+JSON. Here’s Why…
SOAP is a mature protocol with a complete spec and is designed to expose individual operations – or pieces of operations – as web services. One of the most important characteristics of SOAP is that it uses XML rather than HTTP to define the content of the message.
SOAP is still offered by some very prominent tech companies for their APIs (Salesforce, Paypal, Docusign). One of the main reasons: legacy system support. If you built a connector between your application and Salesforce back in the day, there’s a decent probability that connection was built in SOAP.
There are a few additional situations:
- SOAP is good for applications that require formal contracts between the API and consumer since it can enforce the use of formal contracts by using WSDL (Web Services Description Language).
- Additionally, SOAP has built in WS-Reliable messaging to increase security in asynchronous execution and processing.
- Finally, SOAP has built-in stateful operations. REST is naturally stateless, but SOAP is designed to support conversational state management.
Some would argue that because of these features, as well as support for WS_AtomicTransaction and WS_Security, SOAP can benefit developers when there is a high need for transactional reliability.
And yet, most new APIs are built in REST+JSON. Why?
First, REST is easy to understand: it uses HTTP and basic CRUD operations, so it is simple to write and document. This ease of use also makes it easy for other developers to understand and write services against.
REST also makes efficient use of bandwidth, as it’s much less verbose than SOAP. Unlike SOAP, REST is designed to be stateless, and REST reads can be cached for better performance and scalability.
REST focuses on resource-based (or data-based) operations and inherits its operations (GET, PUT, POST, DELETE) from HTTP. This makes it easy for both developers and web-browsers to consume it, which is beneficial for public APIs where you don’t have control over what’s going on with the consumer. Simplicity is one of the strongest reasons that major companies like Amazon and Google are moving their APIs from SOAP to REST.
APIs used by apps that require a lot of back-and-forth messaging should always use REST. For example, mobile applications. If a user attempts to upload something to a mobile app (say, an image to Instagram) and loses reception, REST allows the process to be retried without major interruption, once the user regains cell service.
However, with SOAP stateful operations, the same type of service would require more initialization and state code. Because REST is stateless, the client context is not stored on the server between requests, giving REST services the ability to be retried independently of one another.
REST allows easy, quick calls to a URL for fast return responses. The difference between SOAP and REST, in this case, is complexity—-SOAP services require maintaining an open stateful connection with a complex client. REST, in contrast, enables requests that are completely independent of each other. The result is that testing with REST is much simpler.
Helpfully, REST services are now well-supported by tooling. The available tools and browser extensions make testing REST services continually easier and faster.
Stormpath is an REST+JSON API-based authentication and user management system for your
web and mobile services and APIs. We <3 REST+JSON.
If you want to learn more about how to build, design, and secure REST+JSON APIs, here are some developer tutorials and educational blogposts on REST+JSON API Development:
- Beautiful REST+JSON API Design – this 90-minute best practices presentation for developers dives deep into REST+JSON API Design. Three-time winner of the JavaOne RockStar Award, and viewed over 250,000 times.
- Handy Slides for Beautiful REST+JSON API Design – no need to take notes!
- Secure Your REST API The Right Way – learn the ins and outs of API Security protocols from OAuth to HTTP Basic Authentication.
- Use Stormpath to Manage your API Authentication – instead of building out API Access Control and Authentication yourself, Stormpath can save your development team a lot of time. Our API Authentication service handles OAuth 2.0 Access Tokens, Bearer Tokens, Authentication to your API, Access Control, Authorization and Token and Key Management and Revocation.