Understanding SOAP and REST Basics And Differences

Simple Object Access Protocol (SOAP) and Representational State Transfer (REST) are two answers to the same question: how to access Web services. The choice initially may seem easy, but at times it can be surprisingly difficult.

SOAP is a standards-based Web services access protocol that has been around for a while and enjoys all of the benefits of long-term use. Originally developed by Microsoft, SOAP really isn’t as simple as the acronym would suggest.

REST is the newcomer to the block. It seeks to fix the problems with SOAP and provide a truly simple method of accessing Web services. However, sometimes SOAP is actually easier to use; sometimes REST has problems of its own. Both techniques have issues to consider when deciding which protocol to use.

Before I go any further, it’s important to clarify that while both SOAP and REST share similarities over the HTTP protocol, SOAP is a more rigid set of messaging patterns than REST. The rules in SOAP are important because without these rules, you can’t achieve any level of standardization. REST as an architecture style does not require processing and is naturally more flexible. Both SOAP and REST rely on well-established rules that everyone has agreed to abide by in the interest of exchanging information.

What Is the Simple Object Access Protocol?

The Simple Object Access Protocol (SOAP) is a lightweight, XML-based protocol for exchanging information in a decentralized, distributed environment. By combining SOAP-based requests and responses with a transport protocol, such as HTTP, the Internet becomes a medium for applications to publish database-backed Web services, such as:

Restaurant listings: Which sushi bars are within five blocks of the Geary Theatre?
Car dealer inquiries: What California dealers have a denim blue Audi TT coupe in stock?
Financial information requests: What stocks in my portfolio are below their 50-day average?
Ticket bookings: What are the two best seats available for Miss Saigon next week?
SOAP has a looser coupling between the client and the server than some similar distributed computing protocols, such as CORBA/IIOP, and it provides easier communication for a client and server that use different languages. SOAP exposes a standard way for processes to communicate, yet it leverages existing technologies.

SOAP requests are easy to generate, and a client can easily process the responses. One application can become a programmatic client of another application's services, with each exchanging rich, structured information. The ability to aggregate powerful, distributed Web services allows SOAP to provide a robust programming model that turns the Internet into an application development platform.

SOAP has the following features:

1. Protocol independence
2. Language independence
3. Platform and operating system independence

See Also:
http://www.w3.org/TR/SOAP for information on Simple Object Access Protocol (SOAP) 1.1 specification

How Does SOAP Work?

The SOAP specification describes a standard, XML-based way to encode requests and responses, including:

1. Requests to invoke a method on a service, including in parameters
2. Responses from a service method, including return value and out parameters
3. Errors from a service

SOAP describes the structure and data types of message payloads by using the emerging W3C XML Schema standard issued by the World Wide Web Consortium (W3C). SOAP is a transport-agnostic messaging system; SOAP requests and responses travel using HTTP, HTTPS, or some other transport mechanism.

Figure 1-1 illustrates the components in the SOAP architecture. In general, a SOAP service remote procedure call (RPC) request/response sequence includes the following steps:

1. A SOAP client formulates a request for a service. This involves creating a conforming XML document, either explicitly or using Oracle SOAP client API.
2. A SOAP client sends the XML document to a SOAP server. This SOAP request is posted using HTTP or HTTPS to a SOAP Request Handler running as a servlet on a Web server. Example 1-1 shows the body of a SOAP message, an XML document, that represents a SOAP request for a service that provides an address from an address book.
3. The Web server receives the SOAP message, an XML document, using the SOAP Request Handler Servlet. The server then dispatches the message as a service invocation to an appropriate server-side application providing the requested service.
4. A response from the service is returned to the SOAP Request Handler Servlet and then to the caller using the standard SOAP XML payload format. Example 1-2 contains the body of a response to the request made in Example 1-1.

See Also:
http://www.w3.org/TR/SOAP
http://www.w3.org/XML/Schema for information on XML Schema

Figure 1-1 Components of the SOAP Architecture

This graphic shows the path of a SOAP request and a SOAP response between the SOAP Client and the SOAP Server. The SOAP request is sent from the system running the SOAP Client, going out over the Internet as a SOAP request. The SOAP server receives the request, possibly through a firewall, and passes the service request to the SOAP Service. The SOAP Server then sends the SOAP response over the Internet and back to the SOAP client.

The SOAP specification does not describe how the SOAP server should handle the content of the SOAP message body. The content of the body may be handed to a SOAP service, depending on the SOAP server implementation.

Example 1-1 SOAP Request for Address Book Listing Service

<soap-env:envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:body>
<ns1:getaddressfromname soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:www-oracle-com:AddressBook" xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<nametolookup xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xsi:type="xsd:string">
John B. Good
</nametolookup>
</ns1:getaddressfromname>
</soap-env:body>
</soap-env:envelope>

Example 1-2 SOAP Response from Address Book Service

<soap-env:envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:body>
<ns1:getaddressfromnameresponse soap-env:encodingstyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:www-oracle-com:AddressBook">
<return xmlns:ns2="urn:xml-soap-address-demo" xsi:type="ns2:address">
<city xsi:type="xsd:string">Anytown
</city>
<state xsi:type="xsd:string">NY
</state>
<phonenumber xsi:type="ns2:phone">
<areacode xsi:type="xsd:int">123
</areacode>
<number xsi:type="xsd:string">7890
</number>
<exchange xsi:type="xsd:string">456
</exchange>
</phonenumber>
<streetname xsi:type="xsd:string">Main Street
</streetname>
<zip xsi:type="xsd:int">12345</zip>
<streetnum xsi:type="xsd:int">123
</streetnum>
</return>
</ns1:getaddressfromnameresponse>
</soap-env:body>
</soap-env:envelope>

Why Use SOAP?

Why do we need a standard like SOAP? By exchanging XML documents over HTTP, two programs can exchange rich, structured information without the introduction of an additional standard such as SOAP to explicitly describe a message envelope format and a way to encode structured content.

SOAP provides a standard so that developers do not have to invent a custom XML message format for every service they want to make available. Given the signature of the service method to be invoked, the SOAP specification prescribes an unambiguous XML message format. Any developer familiar with the SOAP specification, working in any programming language, can formulate a correct SOAP XML request for a particular service and understand the response from the service by obtaining the following service details.

• Service name
• Method names implemented by the service
• Method signature of each method
• Address of the service implementation (expressed as a URI)

Using SOAP streamlines the process for exposing an existing software component as a Web service since the method signature of the service identifies the XML document structure used for both the request and the response.

See Also:
http://www.w3.org/Addressing for information on URIs, naming, and addressing

What is a REST API?

REST or RESTful API design (Representational State Transfer) is designed to take advantage of existing protocols. While REST can be used over nearly any protocol, it usually takes advantage of HTTP when used for Web APIs. This means that developers do not need to install libraries or additional software in order to take advantage of a REST API design. REST API Design was defined by Dr. Roy Fielding in his 2000 doctorate dissertation. It is notable for its incredible layer of flexibility. Since data is not tied to methods and resources, REST has the ability to handle multiple types of calls, return different data formats and even change structurally with the correct implementation of hypermedia.

This freedom and flexibility inherent in REST API design allow you to build an API that meets your needs while also meeting the needs of very diverse customers. Unlike SOAP, REST is not constrained to XML, but instead can return XML, JSON, YAML or any other format depending on what the client requests. And unlike RPC, users aren’t required to know procedure names or specific parameters in a specific order.

However, there are drawbacks to REST API design. You can lose the ability to maintain state in REST, such as within sessions, and it can be more difficult for newer developers to use. It’s also important to understand what makes a REST API RESTful, and why these constraints exist before building your API. After all, if you do not understand why something is designed in the manner it is, you can hinder your efforts without even realizing it.

Understanding REST API Design

While most APIs claim to be RESTful, they fall short of the requirements and constraints asserted by Dr. Fielding. There are six key constraints to REST API design to be aware of when deciding whether this is the right API type for your project.

Client-Server

The client-server constraint works on the concept that the client and the server should be separate from each other and allowed to evolve individually and independently. In other words, I should be able to make changes to my mobile application without impacting either the data structure or the database design on the server. At the same time, I should be able to modify the database or make changes to my server application without impacting the mobile client. This creates a separation of concerns, letting each application grow and scale independently of the other and allowing your organization to grow quickly and efficiently.

Stateless

REST APIs are stateless, meaning that calls can be made independently of one another, and each call contains all of the data necessary to complete itself successfully. A REST API should not rely on data being stored on the server or sessions to determine what to do with a call, but rather solely rely on the data that is provided in that call itself. Identifying information is not being stored on the server when making calls. Instead, each call has the necessary data in itself, such as the API key, access token, user ID, etc. This also helps increase the API’s reliability by having all of the data necessary to make the call, instead of relying on a series of calls with server state to create an object, which may result in partial fails. Instead, in order to reduce memory requirements and keep your application as scalable as possible, a RESTful API requires that any state is stored on the client—not on the server.

Cache

Because a stateless API can increase request overhead by handling large loads of incoming and outbound calls, a REST API should be designed to encourage the storage of cacheable data. This means that when data is cacheable, the response should indicate that the data can be stored up to a certain time (expires-at), or in cases where data needs to be real-time, that the response should not be cached by the client. By enabling this critical constraint, you will not only greatly reduce the number of interactions with your API, reducing internal server usage, but also provide your API users with the tools necessary to provide the fastest and most efficient apps possible. Keep in mind that caching is done on the client side. While you may be able to cache some data within your architecture to perform overall performance, the intent is to instruct the client on how it should proceed and whether or not the client can store the data temporarily.

Uniform Interface

The key to the decoupling client from server is having a uniform interface that allows independent evolution of the application without having the application’s services, models, or actions tightly coupled to the API layer itself. The uniform interface lets the client talk to the server in a single language, independent of the architectural backend of either. This interface should provide an unchanging, standardized means of communicating between the client and the server, such as using HTTP with URI resources, CRUD (Create, Read, Update, Delete), and JSON.

Layered System

As the name implies, a layered system is a system comprised of layers, with each layer having a specific functionality and responsibility. If we think of a Model View Controller framework, each layer has its own responsibilities, with the models comprising how the data should be formed, the controller focusing on the incoming actions and the view focusing on the output. Each layer is separate but also interacts with the other. In REST API design, the same principle holds true, with different layers of the architecture working together to build a hierarchy that helps create a more scalable and modular application.

A layered system also lets you encapsulate legacy systems and move less commonly accessed functionality to a shared intermediary while also shielding more modern and commonly used components from them. Additionally, the layered system gives you the freedom to move systems in and out of your architecture as technologies and services evolve, increasing flexibility and longevity as long as you keep the different modules as loosely coupled as possible. There are substantial security benefits of having a layered system since it allows you to stop attacks at the proxy layer, or within other layers, preventing them from getting to your actual server architecture. By utilizing a layered system with a proxy, or creating a single point of access, you are able to keep critical and more vulnerable aspects of your architecture behind a firewall, preventing direct interaction with them by the client. Keep in mind that security is not based on single “stop all” solution, but rather on having multiple layers with the understanding that certain security checks may fail or be bypassed. As such, the more security you are able to implement into your system, the more likely you are to prevent damaging Attacks.

Code on Demand

Perhaps the least known of the six constraints, and the only optional constraint, Code on Demand allows for code or applets to be transmitted via the API for use within the application. In essence, it creates a smart application that is no longer solely dependent on its own code structure. However, perhaps because it’s ahead of its time, Code on Demand has struggled for adoption as Web APIs are consumed across multiple languages and the transmission of code raises security questions and concerns. (For example, the directory would have to be writeable, and the firewall would have to let what may normally be restricted content through.)

Together, these constraints make up the theory of Representational State Transfer, or REST. As you look back through these you can see how each successive constraint builds on top of the previous, eventually creating a rather complex—but powerful and flexible—application program interface. But most importantly, these constraints make up a design that operates similarly to how we access pages in our browsers on the World Wide Web. It creates an API that is not dictated by its architecture, but by the representations that it returns, and an API that—while architecturally stateless—relies on the representation to dictate the application’s state.

For further reading:

1. Why Use REST? 
2. Automatic REST
3. Creating a PHP REST Application Using Laravel and MySQL
4. How to Implement PHP REST API to Connect Different Applications Easily
5. PHP Tutorial with MySQL: REST APIs

Sources:
https://www.mulesoft.com/resources/api/what-is-rest-api-design
https://docs.oracle.com/cd/A97335_02/integrate.102/a90297/overview.htm
https://smartbear.com/blog/test-and-monitor/understanding-soap-and-rest-basics/