SOAP vs. REST APIs: The Key Differences Explained for Beginners

Choosing REST vs. SOAP is a tough step in the API process if you’re a beginner. SOAP and REST are different approaches to data transmission for APIs.

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 effectively? That depends on how you build the API. Let’s go over the two most common methods below, SOAP and REST. Then, we'll compare the differences in detail.

What is SOAP?

SOAP, which stands for Simple Object Access Protocol, is a highly strict and secure way to build APIs that encodes data in XML.

What is REST?

REST, which stands for Representational State Transfer, is a simpler and more flexible method for building APIs. REST APIs can transfer data in a variety of formats, including XML, as well as plain text, HTML, and JSON.

Check out this post for more on REST APIs.

REST and SOAP are two different ways to connect applications with server-side data. Both of the API formats use data that both humans and machines can read, and both often use HTTP protocols. But there are many differences between the two.

The graphic below outlines some REST vs. SOAP differences.

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."

SOAP supports WS specifications like:

• WS-Addressing
• WS-Policy
• WS-Security
• WS-Federation
• WS-ReliableMessaging
• WS-Coordination
• WS-AtomicTransaction
• WS-RemotePortlets

Because of this, 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 REST vs. SOAP 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==

The server will return an HTTP status code and information on the defect. In the example below, there’s an HTTP status code 200 to show the request was successful as well as a JSON object with info on the defect:

 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1758

{
"id": 17,
"title": "Floating toolbar improvements",
"status": "Resolved",
"__permissions": {
"acl": 7
},
"act_finish": "2015-06-31T00:00:00.0000000",
"act_hrs": 0,
"act_start": "2015-06-17T00:00:00.000000",
"actual_results": "The design of the floating toolbar is inconsistent.",
"assigned_to_name": "Smith, John",
"assignee_user_id": 27942,
"closed_by": 27942,
"custom_fields": [
{
"Id": "Custom1",
"Name": "Components",
"Value": "UI"
},
{
"Id": "Custom2",
"Name": "Fixed in build",
"Value": "1.0.13"
}
],
"date_closed": "0001-01-01T00:00:00.0000000",
"date_created": "2015-05-26T10:54:21.0930000",
"date_opened": "2015-05-27T11:42:29.1700000",
"date_resolved": "2015-06-24T09:55:25.4500000",
"date_updated": "2015-06-24T09:55:25.4500000",
"description": "The design of the floating toolbar needs improvement",
"est_finish": "0001-01-01T00:00:00.0000000",
"est_hrs": 0,
"est_hrs_remaining": 0,
"est_start": "0001-01-01T00:00:00.0000000",
"expected_results": "This should work",
"folder_id": 52359,
"folder_name": "UI Defects",
"functional_area_code": "",
"how_found_code": "Code Review",
"import_id": 0,
"issue_code": "Code Defect",
"nbr_events": 0,
"nbr_files": 1,
"nbr_notes": 1,
"nbr_tasks": 0,
"opened_by": 27942,
"opened_by_company": "EDGB",
"opened_by_email": "smith.john@edgb.com",
"opened_by_name": "Smith, John",
"original_id": 0,
"owner_name": "Smith, John",
"owner_user_id": 27942,
"pct_complete": 0,
"priority_code": "1-Fix ASAP",
"project_id": 11873,
"resolution": "Toolbar is redesigned",
"resolution_code": "Fixed",
"resolved_by": 27942,
"resolved_by_name": "Smith, John",
"severity_code": "1-Crash",
"software_version_code": "1.0",
"steps_to_repro": "step 1\r\nstep 2\r\nstep 3\r\nstep 3.1\r\nstep 3.2\r\n",
"update_user_id": 27942,
"user_name": "Smith, John"
}

Notice that this response is not as long as the response given by the SOAP API. Since REST APIs typically send back responses with less data and in the JSON format, they require less bandwidth to use than SOAP APIs.

For specific use cases of when to use SOAP vs REST, keep reading.

When to Use SOAP

Developing private APIs, especially for large enterprises.

SOAP allows data to be transferred in a decentralized, distributed environment. It also has lots of web security mechanisms. These qualities make it ideal for enterprise solutions.

Working with stateful operations.

Unlike calls to REST APIs, calls to SOAP APIs are stateful. This means the server stores information about the client and uses that information over a series of requests or chain of operations.

While this requires more server resources and bandwidth, it’s important if performing repetitive or chained tasks, like bank transfers.

Using an underlying transport protocol other than HTTP.

SOAP is independent of an underlying transport protocol, so you don’t have to use HTTP. Instead, you could use SMTP (Simple Mail Transfer Protocol), JMS (Java Messaging Service), or another transport protocol, depending on your application.

When to Use REST

Developing public APIs.

Many consider REST APIs easier to use and adopt than SOAP APIs. which makes them ideal for creating public web services. REST also lacks some built-in security features that SOAP has — but they aren’t necessary when working with public data and services.

Working with limited server resources and bandwidth.

All calls to a REST API must be stateless. This means that every interaction is independent so each request and response provides all the information required to complete that interaction. Since the server interprets every request as brand new, the server does not store information on past requests.

This greatly reduces the amount of server memory needed. It improves performance since the server is not required to take additional action or retrieve past data when fulfilling a request.

Because REST is stateless, data can be cached, which also saves server resources and bandwidth.

Finally, REST APIs can use different data formats, like JSON, which is lighter than XML. This makes them faster and more efficient than most SOAP APIs.

Building mobile applications.

Because REST is lightweight, efficient, stateless, and cacheable, it’s ideal for building mobile applications.

Deciding Between REST vs. SOAP

There’s no golden rule for building APIs. Deciding between SOAP vs. REST when building APIs depends on a variety of factors, including what programming language you use and how much time you have to build it.

Editor's note: This post was originally published in September 2021 and has been updated for comprehensiveness.