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: The Granddaddy of Web Services Interfaces

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.

The Argument For SOAP

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.

REST + JSON: The Easy Way to Expose Web Services

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 supports many data formats, but the predominant use of JSON means better support for browser clients. JSON sets a standardized method for consuming API payloads so that you can take advantage of its connection to JavaScript and the browser. Read our best practices on REST+JSON API Design Here.

So, when should you use REST vs SOAP?

Case 1: Developing a Public API

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.

Case 2: Extensive Back-and-Forth Object Information

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.

Case 3: Your API Requires Quick Developer Response

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.

Developer Resources for REST+JSON API Development

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:

Like what you see? to keep up with the latest releases.