9.3. SOAP vs REST

*Under construction
A more up-to-date description of the Transaction standards will follow in due time.

Introduction

The choice of a specific technical solution or application remains the responsibility of the individual party who develops an API, which is why the API-framework description is kept neutral with regard to technology and architecture.
Existing transaction standards have been taken into account in order to preserve investments made in the past, and new technological developments and commonly used best practices have been considered.
The first generation of web services was based on SOAP (Simple Object Access Protocol), whereas the newer generation of (web) APIs is based on the REST architecture style, also referred to as “RESTful API”.
In both SOAP and REST based implementations, the Hypertext Transfer Protocol (HTTP) is used as the means of transport over the internet. This chapter will therefore briefly consider both the SOAP and REST standards, as well as the main differences between them from a technical point of view, functional differences are covered in the chapter Domain specific functions.

SOAP vs REST

One of the important differences between a REST/JSON and SOAP/XML based architecture is the way the functions and message content is structured.
The SOAP protocol is based on a webservice request in xml which holds information about schema’s, definitions and functions in the upper layer at the level of the soap envelope, with the actual business/process content stored inside the envelope.

The REST architecture is simpler in the sense that it uses the functions already available in the HTTP protocol to Create, Read, Update and Delete data with the POST, GET, PUT and DELETE commands.
When the HTTP connection is made, the intention of the webservice call is already determined by one of these functions. The actual content is presented directly in the message body.
This is usually but not exclusively in JSON format; a REST call can also contain content in XML format for example.
Contrary to a SOAP implementation, the REST message does not have a specific envelope. The function is defined by the HTTP command and the content is stored in the message body.

Another difference is the way parameters are used to direct the handling of a message and the processing of its content. The REST architecture makes use of the standard parameters to control the HTTP transaction. Some of the most common parameters concern autorization, and the types of format and encoding which are available/used.
Parameters which are related to the content of the message are defined as header parameters and are integrated in the url.
For example a POST command that uses the path parameter to specify a part of the url, or the query parameter which is used to define the requested content in a GET command.

Best practice

It is not a question of one architecture or solution being better than the other. Depending on the circumstances and the purpose for which either a SOAP or REST implementation is used, each option has certain advantages and disadvantages. Over the past years, the number of REST-based API implementation has rapidly outgrown the number of SOAP-based implementations which is rapidly declining. Currently over 80% of the centrally registered APIs are REST-based. (source).