Much of the discourse about web APIs is characterized by a debate of what REST offers compared to SOAP. To help you understand the context of this debate, it is important to state why REST has become the prevalent style for implementing web APIs.
REST (Representational State Transfer) is embodied in the majority of web APIs available for application developers to consume. It was originally proposed by Roy Fielding in his dissertation “Architectural Styles and the Design of Network-based Software Architectures” with many elements being subsequently formalized by World Wide Web Consortium (W3C) as part of HTTP/1.1.
The dissertation outlined a framework by which software could be understood in the context of its architecture and the specific relevance of this framework to network-based application architectures (such as the World Wide Web). It introduced REST as an exemplar of this approach.
The REST example described several key principles (described by Fielding as constraints) that aimed to elucidate the software engineering design decisions made in its formulation. It is these principles that characterize most of REST-based APIs in use today:
- Precedence of the client-server relationship
- Requirement for stateless communication
- Implementation of cache constraints to engender efficiencies in network communications
- Use of a uniform interface through standardized data elements such as resources and representations
The question that you might ask about the rise of the REST paradigm is why has it become the prevalent style for web APIs? Briefly, because much information is already available about this subject, there are several reasons:
- The common perception is that REST offers a lightweight alternative to service-orientated mechanisms such as SOAP. It eschews the protocol-based interfaces that SOAP/WSDL creates and focuses on discrete objects defined using resources (namely URIs) in conjunction with HTTP methods. This is an attractive quality for the original target audience of web APIs.
- The growth in the use of REST for web APIs has also been coupled with the growth of mobile apps. Neither Android nor iOS support SOAP natively whereas both support the building blocks to implement REST.
- REST is expressed in terms of the distributed architecture that sets its context, HTTP. For that reason, much of the functionality required to implement CRUD-like semantics is ready to use. This allows the API developer to concentrate on the provision of objects through resources without overloading their interface with the verbiage required to express operations. For example, each of GET, POST, PUT, and DELETE on a customer record would need to be defined as individual operations in a WSDL document when using SOAP, whereas with REST the interface is consistent for each method.
- REST allows for the fine-grained control of objects through the use of resources (expressed as URIs) that also allows for greater efficiency in communications with the server (obviously important when implemented on a mobile device). The consumer of the API has the ability to make a choice to either update all or part of this object. The actual interface does not change, only what they choose to update.
The reasons outlined start to set the context for why design decisions were made in the creation of web APIs that opted for REST, in that REST fulfilled specific requirements that were not pragmatic to approach using existing technologies such as SOAP.
However, REST does not render the use of SOAP redundant. Many web APIs implement SOAP and it will continue to be an important building block for enterprise service integration particularly in organizations that implemented SOA. One of the roles of web APIs and REST in such cases is complementary to the existing services, to allow services to be exposed to external consumers in a manner they can make sense of.
The decision you make should be in the context of the specific requirements you are aiming to address rather than one based on pure technical merit.
To learn more please read the Redbook here.