SOAP vs REST APIs: The Key Differences Explained for Beginners

Do you want to connect your app to Instagram to repost images using specific hashtags, or to Facebook so it can automatically create posts? Or maybe you want to embed YouTube videos on your website? You can do all of these things and more with application programming interfaces (APIs).

APIs, like the Instagram API, Facebook API, and YouTube API, provide a secure and standardized way for different software to “talk” to each other. Meaning, an application can extract functionality or data from another piece of software and use it to enhance its own functionality or UX.

But how do applications make these requests, process them, and answer them in a way that the other understands? That depends on how the API was built. Let’s go over the two most common methods below.

Now that we have a high-level overview of the differences between SOAP and REST, let’s take a closer look at how they compare in terms of services, security, and examples.

• SOAP vs REST Services
• SOAP vs REST Security
• SOAP vs REST Examples
  • REST Example

SOAP vs REST Services

To compare SOAP and REST APIs, we first have to understand what each type of API does exactly.

SOAP Services

SOAP is a standard communication protocol system that uses XML technologies to define an extensive messaging framework that allows structured information to be exchanged in a decentralized, distributed environment. In other words, SOAP allows applications running on different operating systems to communicate using different technologies and programming languages.

A client can use SOAP APIs to create, retrieve, update or delete records, such as passwords, accounts, leads, and custom objects, from a server.

REST Services

REST, on the other hand, is an architectural style, not a protocol. As stated above, it stands for Representational State Transfer. That means, when a client requests a resource using a REST API, the server transfers back the current state of the resource in a standardized representation. In other words, REST APIs receive requests for a resource and return all relevant information about the resource in a format that clients can easily interpret.

In addition to requesting resources, clients can use REST APIs to modify and even add new items on a server using HTTP methods.

For a more in-depth description, read REST APIs: How They Work and What You Need to Know.

SOAP vs REST Security

Now that we have a better understanding of what SOAP and REST APIs do, let’s compare their security measures and protocols.

SOAP Security

Since SOAP is a messaging protocol, securing SOAP APIs is primarily focused on preventing unauthorized access to the messages (and users’ information contained within those messages) received by and sent from SOAP APIs. The main defense against unauthorized access is Web Standards (WS) Security, a set of principles that regulate the confidentiality and authentication procedures for SOAP messaging. WS Security-compliant measures include passwords, XML encryption, and security tokens, among other mechanisms.

WS Security goes beyond traditional web security mechanisms, such as HTTPS, which only secures messages during the transport between the client that made the request and the server or web service that has the data being requested. WS Security, on the other hand, secures messages beyond the HTTPS connection and sometimes even beyond the transport layer.

How does it do this, exactly?

A SOAP message either contains the information needed to secure it, or contains information about where to get the information needed to secure it. A SOAP message also contains information relevant to the protocols and procedures for processing the specified message-level security in its header. That means when a web service endpoint receives a SOAP message, it verifies the security information in the header to make sure it has not been tampered with. That’s why SOAP is said to have “message-level security.”

Because SOAP supports WS specifications, like WS-Addressing, WS-Policy, WS-Security, WS-Federation, WS-ReliableMessaging, WS-Coordination, WS-AtomicTransaction, and WS-RemotePortlets, SOAP APIs are ideal for internal data transfers and other sensitive tasks — but unnecessary for using a public web service that’s freely available to everyone, like retrieving weather data. We’ll talk more about when to use SOAP vs REST APIs later in the post.

REST Security

REST APIs only support traditional web security mechanisms, such as HTTPS. That means when an application sends and retrieves a message from a REST API using HTTPS, the message is secured only for the HTTPS connection. Meaning, the message is secured only during the transport between the client and the service. That’s fine for public web services, but may not be enough for more sensitive data transfers.

Since REST APIs don’t have the built-in security capabilities or extensions that SOAP has, their security depends on the design of the APIs themselves. REST APIs can be designed with certain security mechanisms that ensure that only authenticated and authorized users can access them. Common REST API authentication methods are HTTP basic authentication, JSON web tokens, OAuth, and API keys.

REST APIs should also have detailed specifications and reject any requests that don’t have the correct declarations in their HTTP headers, for example, or otherwise follow their specifications. This will help protect the underlying web application from malformed and malicious inputs, even after the client has gained access.

SOAP vs REST Examples

Let’s compare some examples of requests and responses to and from a SOAP API and a REST API. The examples below are based on the QAComplete SOAP API and REST API, respectively. QAComplete is a comprehensive software test management tool by SmartBear.

SOAP Example

QAComplete SOAP requests are HTTP POST requests made to the web service endpoint URL. The client and server exchange data in the XML format in the body of HTTP requests and responses.

This SOAP API only accepts HTTP POST requests but it also supports several common operations for all item types, including Add, Delete, Load, LoadByCriteria, and Update. You’ll see these operations instead of the HTTP verbs GET, PUT, PATCH, and DELETE.

The sample code below is requesting to get a defect by its ID in a project in QAComplete using the SOAP API. The code snippet is written in XML and uses the Bugs_Load operation:

 
POST /psws/psws.asmx HTTP/1.1
Host: myteam.mysite.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 486 {Insert an appropriate value here}

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<Bugs_Load xmlns="http://www.pragmaticsw.com/">
<AuthenticationData>
<AppCode>agSP</AppCode>
<DeptId>7154</DeptId>
<ProjId>1032</ProjId>
<UserId>25315</UserId>
<PassCode>p@ssword</PassCode>
</AuthenticationData>
<BugId>5</BugId>
</Bugs_Load>
</soap12:Body>
</soap12:Envelope>

The response will contain an HTTP status code and a Bug object containing information on the needed defect. It will be written in XML. In the example below, there’s an HTTP status code 200 to show the request was successful as well as info on the defect in XML:

 
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 2244 {The server returns an appropriate value here}

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<Bugs_LoadResponse xmlns="http://www.pragmaticsw.com/">
<Bugs_LoadResult>
<CustomFields>
<string>0.9.19</string>
<string>1.0.24</string>
</CustomFields>
<CustomFieldNames>
<string>Found in build</string>
<string>Fixed in build</string>
</CustomFieldNames>
<BugId>13254</BugId>
<Title>Floating toolbar improvements</Title>
<StatusCode>Resolved</StatusCode>
<PriorityCode>2-Fix Soon</PriorityCode>
<HowFoundCode>Test-Ad hoc</HowFoundCode>
<ResolutionCode>Fixed</ResolutionCode>
<AssigneeUserId>27942</AssigneeUserId>
<OpenedBy>27568</OpenedBy>
<ClosedBy>27942</ClosedBy>
<ResolvedBy>27568</ResolvedBy>
<Description><![CDATA[The design of the floating toolbar needs improvement so that it’s clearer what the user needs to do.]]></Description>
<Resolution>Resolved by Susan McLaren on 24-Jun-2014 at 03:55 PM</Resolution>
<OwnerUserId>27572</OwnerUserId>
<TestCaseId>0</TestCaseId>
<FolderId>52359</FolderId>
<EstHrs>0.000</EstHrs>
<EstStart>2014-06-10T10:00:00</EstStart>
<EstFinish>2014-06-13T10:00:00</EstFinish>
<PctComplete>100</PctComplete>
<ActHrs>0.000</ActHrs>
<ActualStart>2014-06-17T00:00:00</ActualStart>
<ActFinish>2014-06-31T00:00:00</ActFinish>
<EstHrsRemaining>0.000</EstHrsRemaining>
<DateOpened>2014-05-26T15:54:21.093</DateOpened>
<DateResolved>2014-06-24T15:55:25</DateResolved>
<DateClosed>0001-01-01T00:00:00</DateClosed>
<DateUpdated>2014-06-31T05:54:22</DateUpdated>
<ProjId>17823</ProjId>
<DateCreated>2014-05-26T15:54:21.093</DateCreated>
<UpdateUserId>27534</UpdateUserId>
<OriginalId>0</OriginalId>
<ImportId>0</ImportId>
<AssignedToName>Doe, John</AssignedToName>
<OpenedByName>McLaren, Susan</OpenedByName>
<OpenedByEmail>susan@example.com</OpenedByEmail>
<OpenedByCompany>Edgar Solutions</OpenedByCompany>
<ResolvedByName>McLaren, Susan</ResolvedByName>
<UserName>Fry, Alex</UserName>
<OwnerName>Davis, Eugeny</OwnerName>
<NbrFiles>0</NbrFiles>
<NbrNotes>1</NbrNotes>
<NbrEvents>0</NbrEvents>
<NbrTasks>2</NbrTasks>
<FolderName>FamilyAlbum/Release 1.1/Iteration 1</FolderName>
</Bugs_LoadResult>
</Bugs_LoadResponse>
</soap12:Body>
</soap12:Envelope>

Notice that this SOAP message contains an envelope, header, and body element, all of which are required.

REST Example

REST requests are HTTP requests made to the the endpoint URL of QAComplete REST API, which has the following format: http(s)://{your-server}/rest-api/service/api/{version}/{resource}. This API uses the HTTP methods GET, POST, PUT, PATCH, and DELETE.

The sample code below is requesting to get a defect by its ID in a project in QAComplete using the QAComplete REST API. The code snippet is written in JSON and uses the HTTP method, GET:

 
GET http://yourserver.com/rest-api/service/api/v1/projects/11873/defects/17 HTTP/1.1
Host: yourserver.com
Connection: keep-alive
Accept: application/json
Authorization: Basic am9obkBleGFtcGxlLmNvbTpwQHNzd29yZA==