SOAP vs. REST APIs: Understand the Key Differences

Computer SOAP vs. REST APIs: Understand the Key Differences

These days, it’s more true than ever that “no company is an island.” From social logins to selling their data, many businesses rely on each other by exchanging information over the Internet–and much of that exchange is done via an API. When delving deeper into the question of developing APIs, you’ll undoubtedly encounter the question: SOAP or REST? Although REST APIs have become the most popular choice for today’s businesses, the decision isn’t always an easy one. In this article, we’ll go over everything you need to know about SOAP and REST APIs, so that you can come to the conclusion that’s ultimately right for your situation.

What is an API?

There are a lot of definitions of the term “API” out there, and many can leave you feeling more confused than before you read them. At its core, an API (application program interface) is a way for you to get the information that you need from a website in a consistent format. You can think of an API as like an interaction between a business and a customer, such as placing an order at a restaurant or getting cash from an ATM.
  • Customers first read the menu or the ATM screen. Then, they decide what food they would like to order, or what transaction they would like to select.
  • The waiter or ATM serves as the “middleman” between the customer and the business. They take the request from the customer and present it to the business in the way that’s most comprehensible and efficient.
  • The business reviews the request and sends back a response to the customer, such as a plate of food or the customer’s account balance.
It’s important to note that in both of these examples, the interaction is entirely predictable. When customers go to a restaurant, they can assume that they’ll be presented with a menu, use that menu to place an order, and receive the food that they ordered. Meanwhile, most ATMs have a similar user interface that customers can easily navigate in order to withdraw money and check their balance. In the same way, APIs offer consistency and regularity to users who want to query a website for its data. By establishing a common set of rules for exchanging information, APIs make it easier for two parties to communicate. Suppose that you want to download 100 different articles from Wikipedia. You’d also like to know the date that each page was created, and which other Wikipedia pages link to that page. The good news is that you don’t have to visit each page individually and compile this information yourself. Wikipedia offers an API through which it can deliver this data (and more) to the user. You include the name of the article in your API request, and then you can parse the content of the API response to get what you’re looking for: the article text, the creation date, and the list of other pages. Some organizations offer their APIs as a product that other businesses can purchase, such as commercial weather service Weather Underground. The company sells access to its complete weather data and forecasts in the form of an API. Its customers can use that data for their own business purposes and in their own products.

What is a SOAP API?

SOAP (which stands for Simple Object Access Protocol) is an API protocol that uses the XML Information Set specification in order to exchange information. A standard SOAP message consists of the following XML elements:
  • An Envelope element that identifies the document as a valid SOAP message.
  • An optional Header element that specifies additional requirements for the message, such as authentication.
  • A Body element that contains the details of the request or response.
  • An optional Fault element that contains information about any errors encountered during the API request and response.
An example SOAP request for the weather.gov API might look like this:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<SOAP-ENV:Body>

<ns8023:NDFDgenLatLonList xmlns:ns8023="uri:DWMLgen">

<listLatLon xsi:type="xsd:string">
   39.965506,-77.997048 39.916268,-77.947228
</listLatLon>

<product xsi:type="xsd:string">time-series</product>

<startTime xsi:type="xsd:string">2004-01-01T00:00:00</startTime>

<endTime xsi:type="xsd:string">2012-02-12T00:00:00</endTime>

<Unit xsi:type="xsd:string">e</Unit>

<weatherParameters>
   <maxt xsi:type="xsd:boolean">1</maxt>
   <mint xsi:type="xsd:boolean">1</mint>
</weatherParameters>

</ns8023:NDFDgenLatLonList>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>
This simple SOAP API request asks for the minimum and maximum temperatures for two locations in Pennsylvania between 2004 and 2012. As you can see, it contains a base Envelope element, which itself contains a Body element with the details of the request:
  • The “ns8023:NDFDgenLatLonList” element, which contains the latitudes and longitudes of the two locations.
  • The “startTime” and “endTime” elements, which denote the time boundaries of the request.
  • The “weatherParameters” element, which denote the information that we are interested in seeing (here, the maximum and minimum temperatures).

What is a REST API?

REST (which stands for Representational State Transfer) is an architectural style for APIs that relies on the HTTP protocol and JSON data format to send and receive messages. Let’s use the example of the API for the copywriting marketplace Scripted.com. If you want to get all of the writing jobs that a particular business has ordered, for example, then you would make the following REST API request:
GET https://api.scripted.com/abcd1234/v1/jobs
where “abcd1234” is replaced with a key that is unique to the organization. With REST APIs, the details of the request–such as the type of request (jobs) and the organization (abcd1234)–are explicitly embedded in the URL itself, rather than being wrapped in an XML document like we saw with SOAP. REST APIs typically send back data in JSON format rather than XML. The corresponding JSON response would look something like:
HTTP/1.1 200 OK{

"id": "5654ec06a6e02a37e7000318",

"topic": "Where to Buy an Orangutan",

"state": "copyediting",

"quantity": 1,

"delivery": "standard",

"deadline_at": "2015-12-04T01:30:00Z",

"created_at": "2015-11-24T23:00:22Z",

"content_format": {

"id": "5654ec02a6e02a37e70000d5",

"name": "Standard Blog Post",

"pitchable": true,

"length_metric": "350-450 words",

},

"pricing": {

"total": 9900

},

"writer": {

"id": "5654ec01a6e02a37e700003b",

"nickname": "Bob L.",

},

"document": {

"id": "5654ec06a6e02a37e700031a",

"type": "Document"

}

}
Here, the HTTP response object contains details about the API request: for example, the title of the article, the length of the article, and the writer assigned to the article.

The Pros and Cons of SOAP and REST

When comparing REST and SOAP, people often use the analogy of a postcard and an envelope. REST is like a postcard in that it’s lightweight and consumes less bandwidth (paper). Meanwhile, SOAP is like an envelope: there’s an extra overhead required on both ends to package and unpackage it. Note that the analogy isn’t perfect: unlike a postcard, the content of REST requests and responses isn’t (necessarily) insecure. Instead, REST uses the security of the underlying transport mechanism, which is usually HTTPS. On the other hand, SOAP implements its own security measure, which is known as WS-Security. Some people believe that REST is largely a “replacement” for SOAP, due to its lower overhead and improved ease of use. According to Cloud Elements’ 2017 State of API Integration report, 83 percent of APIs now use REST, while only 15 percent continue to use SOAP. Some of these businesses primarily use REST, but continue to integrate SOAP APIs into their projects using tools such as DreamFactory’s SOAP connector. However, this conception of SOAP as outmoded isn’t quite accurate. Even as REST becomes the API style of choice for most businesses, SOAP remains a tool that is better-suited for certain use cases, mainly in large enterprises who need  additional extensibility and logic features native to the protocol. The advantages of REST include:
  • Flexibility: Although REST is most commonly implemented with HTTP and JSON, developers are by no means obligated to use them. Websites can send back responses using data formats including JSON, XML, HTML, or even plaintext–whatever best suits their needs.
  • Speed: Because it tends to use much less overhead, REST APIs are typically significantly faster than SOAP. While the differences might be imperceptible for a single request, the disparity grows larger and larger as you place more and more requests.
  • Popularity: REST has reached critical mass on the Internet. Major websites such as Google, Twitter, and YouTube all use REST APIs for users to send and receive messages. Due to this familiarity, it’s typically easier for developers to get up and running with REST.
  • Scalability: Thanks to their speed and simplicity, REST APIs usually perform very well at scale.
Despite the major benefits of using REST, SOAP remains the preferred protocol in certain use cases. Some organizations find that SOAP offers the transactional reliability that they’re looking for, while others simply continue to use SOAP because they need legacy system support. The advantages of SOAP include:
  • Formality: SOAP can use WSDL (Web Services Description Language) to enforce the use of formal contracts between the user and the website. SOAP is also inherently compliant with ACID database standards, which ensures that the transactions it performs will be valid even in the event of errors or hardware issues.
  • Logic: If a REST API request is unsuccessful, it can only be addressed by retrying until the request successfully goes through. On the other hand, SOAP includes built-in successful/retry logic so that the requesting system knows how to behave.
  • Security: SOAP comes with its own security mechanism, WS-Security, built into the protocol. If you want to ensure that your messages are secure, rather than relying on the underlying transport mechanism as does REST, then SOAP may be the right choice.
  • Extensibility: In addition to WS-Security, SOAP includes support for other protocols such as WS-Addressing and WS-ReliableMessaging that can define other standards of communication and information exchange.

Final Thoughts

For most cases, REST should be considered the “default” option as adoption continues to grow across the web. Most public-facing APIs now use REST, because it consumes less bandwidth and its compatibility with HTTP makes it easier for web browsers to use. However, you may find that the additional features and security offered by SOAP are enough to sway your decision. In the end, the “right” choice between SOAP and REST will be highly dependent on your own situation. Even better, the choice of SOAP and REST doesn’t have to be between one and the other. If you want to communicate with REST but still need access to legacy SOAP services, DreamFactory offers the ability to add a REST API onto any database or SOAP API. Reach out to us today to get a free demo from our team of API experts.

AWS Redshift – SQL Functionality on Planet-Scale Hardware

The Problem

Your manager’s peers have been bragging a lot lately about their data warehouses, analytics, and charts, and now a steady stream of data-related questions are being sent your way.  Your department maintains several databases, and the data they contain has the potential to answer everything management is asking for. But the databases are needed for day-to-day operations, and can’t scale to answer these often highly specific questions such as, “How many asparaguses were consumed by men named Fonzie in Cleveland on Tuesdays in 2013?”. How to unlock the potential of this data?

You’ve probably heard of data warehouses, which are tailor-made for this sort of witchcraft. They make it possible to unlock every bit of value from data, and find answers wickedly fast. In the past, creating and maintaining data warehouses meant large, ongoing investments in hardware, software, and people to run them. This would be a hard sell – isn’t the company already spending enough?! Good news, however! In this day of cloud computing, it’s incredibly simple to create, load, and query data warehouses. They typically charge on a usage basis, meaning you don’t need the initial upfront capital investment to get off the ground. And they are super fast – far more powerful than anything you could run in-house.

This post will focus on Amazon Web Services Redshift (Amazon Web Services = AWS). And as a bonus, I’ll demonstrate the incredible Dreamfactory, which automatically builds a slick REST API interface over the top. From there, you’re a GUI away from giving management everything they could ask for, and wowing them with extras they hadn’t even thought of. They can now stand tall amongst their fellow executives, knowing you have their back.

AWS Redshift

AWS Redshift is built upon PostgreSQL, but has been dramatically enhanced to run at “cloud scale” within AWS. There are a few ingredients to this secret sauce:

Column-oriented storage

While you don’t need a deep understanding of what’s happening under the hood to use it, Redshift employs a fascinating approach to achieve it’s mind-boggling performance. Let’s say you have data that looks like the following:
ID NAME CREATED DESCRIPTION AMOUNT

1 Harold 2018/01/01 Membership 10.00

2 Susan 2017/11/15 Penalty 5.00

3 Thomas 2016/10/01 Membership 8.00
Most SQL databases you’ve probably used in the past are row-based, which means they store their data something like this:
1:Harold,2018/01/01,Membership,10.00;

2:Susan,2017/11/15,Penalty,5.00;

3:Thomas,2016/10/01,Membership,8.00;
This is the efficient way to maximize storage, and works well for retrieving data in the “traditional fashion” (rows at a time). But when you want to slice and dice this data, it doesn’t scale very well. If you’ve got large (business-scale) volumes of data, and a variety of ways you want to query it, you can really start to strain your database. Column-based databases, on the other hand, flip this idea on its head, and store the information in a column-based format, with the *data* serving as the *key*. So the above might look something like this:
Harold:1;Susan:2;Thomas:3;

2018/01/01:1;2017/11/15:2;2016/10/01:3;

Membership:1,3;Penalty:2;

10.00:1;5.00:2;8.00:3;
This drastically improves query performance. For example, when searching for “DESCRIPTION == ‘Membership'”, the query only needs to make one database call (“give me the items with a ‘DESCRIPTION’ of ‘Membership'”), instead of inspecting each row individually (as it would have to do in a traditional, row-based database). Very cool, very fast!

Massive Parallelization

When I picture what the AWS cloud must look like, I usually conjure something up from the Matrix (except it’s full of regular computers, rather than, well, humans). Or maybe Star Trek’s “Borg”, a ridiculous planet-cube flying through space, sucking up other civilizations. I guess both of those images are a little disturbing. A safer mental image is this – data centers spanning the globe, loaded with racks and racks of computers, all connected and working together. For most computing tasks, throwing more hardware at the problem doesn’t automatically increase performance. There are bottlenecks that remain in place no matter how many processors are churning away. In our “traditional database” example, this bottleneck is typically disk I/O – the processors are all trying to grab data from the same place. To overcome this, the architecture and storage have to be arranged in a way that can benefit from parallelization. Which is exactly the case with AWS Redshift. Due to the column-based design described above, Redshift is able to take full advantage of adding processors, and it’s almost linearly scalable. This means if you double the number of computers (“nodes”, in Redshift-speak), the performance doubles. And so on. Combine this scalability with the ridiculous number of computers AWS has at it’s disposal (specifically, several Borgs-worth), and it’s like staring out at a starry night. It goes on forever in all directions.

How this works for you

If you’re sold on the power of AWS Redshift, then you’ll be pleased to learn that setup is incredibly simple. AWS documentation is top notch, a crucial thing in this brave new world. When writing this post, I followed their tutorial, and it all went smoothly. Probably took me 15 minutes, and I had the example up and running. If you already have SQL expertise, you won’t have any problem picking up Redshift syntax. There are some differences and nuances, but the standard “things” (joins, where clauses, etc) all work as expected. I typically use Microsoft’s SQL Server Management Studio (SSMS), and was able to connect to Redshift with no problem (after setting it up as a linked server). Your favorite SQL client will presumably work here as well (anything that supports JDBC or ODBC drivers). Once you get your feet wet, there are myriad tools that will load your business data into Redshift. If you’ve got SQL chops in house, I’d start with the AWS documentation, and go from there. If you need a little (or a lot) of help, a whole ecosystem of companies and tools have sprung up around Redshift. A quick Google search will introduce you to them. When you’re up and running, and growing more comfortable demanding more from the system, AWS makes it incredibly simple to add capacity. Thanks to the brilliant Redshift architecture, you just add nodes, and AWS takes care of the rest. Their billing dashboard will show you what it’s costing in real time, with no hidden or creeping costs of data centers, hardware upgrades, things going bump in the night, etc. So much magic happening under the covers, and you get the credit. The joys of cloud computing!

My Humble Example

When writing this, I used the example AWS provides (it consists of a few tables containing some fake Sales data). With everything in place, I can query from SSMS (with a little bit of “linked server” glue syntax):
exec ('-- Find total sales on a given calendar date.

SELECT sum(qtysold)

FROM sales, date

WHERE sales.dateid = date.dateid

AND caldate = ''2008-01-05'';') at redshift

sum

--------------------

210

(1 row affected)
I get a thrill when a chain of systems, architectures, and networks all flow together nicely. Somewhere in a behemoth of a data center, a processor heard my cry, and spun out this result in response. Amazing.

DreamFactory

Now that the company has access to the data, and can gleefully ask any question, they are going to want the dashboards and pretty graphs. Typically you’d use a REST API to feed the data to some sort of UI, but how to do this with Redshift? While management is tickled with their new toy, they will cloud over with suspicion if you now propose a months-long project to make it shinier. In keeping with the theme of “easy, automatic, and powerful”, I’d propose using DreamFactory. In a matter of minutes (literally), it will connect to a data store (both SQL or NoSQL), intelligently parse all the schema, and spin up a REST API layer for doing all the things (complete with attractive documentation). What used to take a team of developers months can now happen in an afternoon! Here are some screenshots of my REST API, completely auto generated from the Redshift example above. It took me about 15 minutes (12 of those spent poking around the documentation) to get this done. For my simple example, I followed their Docker instructions, and in no time was playing with the REST API depicted below:
let’s get our rest on!
 
what pretty documentation you have!
  Powerful stuff!

To Infinity and Beyond!

Now that you’ve witnessed how easily you can warehouse all your data, and bootstrap it into a REST API, it’s time to bring this to your organization. Play with it a little, get comfortable with the tools, then turn up the dials.   Want to learn more about how DreamFactory and Redshift can work together (or how to put a REST API on any database)?  Schedule a demo with us. The next time management comes calling for data, you can give it to them with a fire hose!