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.

Filtering Related Columns within DreamFactory REST API Queries

Consider a query which joins employee records found in an employees table with information about their assigned department, the latter of which resides in a table named departments. The relationship is formalized using a key named emp_no. When DreamFactory parses the schema it will create aliases for each relationship, including one for the above-described named something like dept_emp_by_emp_no. The join query will therefore look like this:
/api/v2/mysql/_table/employees?related=dept_emp_by_emp_no
This would yield a JSON response containing records that look like this:
{
  "emp_no": 10001,
  "birth_date": "1953-09-02",
  "first_name": "Georgi",
  "last_name": "Facello",
  "gender": "M",
  "hire_date": "1986-06-26",
  "birth_year": "1953",
  "dept_emp_by_emp_no": [
    {
      "emp_no": 10001,
      "dept_no": "d005",
      "from_date": "1986-06-26",
      "to_date": "9999-01-01"
    }
  ]
},
If you wanted to limit the related fields to just dept_no and from_date, you would add dept_emp_by_emp_no.fields to the parameter list:
/api/v2/mysql/_table/employees?related=dept_emp_by_emp_no&dept_emp_by_emp_no.fields=dept_no,from_date
This query would yield records with the following structure:
{
  "emp_no": 10001,
  "birth_date": "1953-09-02",
  "first_name": "Georgi",
  "last_name": "Facello",
  "gender": "M",
  "hire_date": "1986-06-26",
  "birth_year": "1953",
  "dept_emp_by_emp_no": [
    {
      "dept_no": "d005",
      "from_date": "1986-06-26"
    }
  ]
},
You can learn more about working with related data inside DreamFactory on our wiki: http://wiki.dreamfactory.com/DreamFactory/Features/Database/Related_Data#Getting_the_Related_Data.

Create a MySQL REST API in Minutes Using DreamFactory

Karl Hughes recently penned a blog post titled “The Bulk of Software Engineering in 2018 is Just Plumbing“. Notably he stated, “Just like plumbers, we are paid to know our tools and understand how they work together to make a usable piece of equipment, not to reinvent working technology…”. As programmers we should not be bothered with repeatedly writing code which is otherwise readily available, robust, and well-tested. Yet this problem remains persistent in the REST API space, despite the implementation process being by this point in time rote, repetitive, and prone to error and oversight. This oversight is costly for several reasons:
  • End users just *do not care* how the API was implemented, meaning there is no competitive advantage to be had by hand-crafting a new API for each project.
  • Error and oversight in the API implementation and deployment phase can come at a very steep price due to security lapses and performance issues.
  • Repeatedly building one-off APIs means they can’t be managed via a single platform or interface; unless the team decides to devote even more time and effort to building a custom management solution.
Fortunately, the DreamFactory platform can easily absolve your team from all of these hassles and much more by offering a centralized solution for the API generation, documentation, and security. In this tutorial I’ll show you just how easy it is to build, secure, and deploy a REST API for your MySQL database.

Follow Along!

DreamFactory’s MySQL service connector is part of our open source version. You can download an installer or clone directly from GitHub via our downloads page.

Generating the MySQL REST API

DreamFactory can generate REST APIs for 18 databases, among them MySQL, Microsoft SQL Server, Oracle, PostgreSQL, and MongoDB. To do so, you’ll login to the DreamFactory administration interface, navigate to Services and then enter the service creation interface by clicking on the Create button located to the left of the screen. From there you’ll select the MySQL service type by navigating to Database > MySQL (see below screenshot).   Next you’ll be prompted to provide a name, label, and description (below screenshot). The latter two are used just for reference purposes within the administration interface, however the name value is particularly important because as you’ll soon see it will comprise part of the API URL.   Finally, click on the Config tab. Here you’ll be prompted to provide the database connection credentials (see below screenshot). This should really be nothing new; you’ll supply a host name, username, password, and database. Additionally, you can optionally specify other configuration characteristics such as driver options, the timezone, and caching preferences. For the purpose of this tutorial I’ll stick to the required fields and leave the optional features untouched.   With the credentials in place, just press the Save button at the bottom of the screen, and believe it or not the REST API has been generated!

Viewing the Swagger Documentation

Along with the API, DreamFactory will also auto-generate an extensive set of interactive Swagger documentation. You can access it by clicking on the API Docs tab located at the top of the administration interface, and then selecting the newly generated service by name. You’ll be presented with 44 endpoints useful for executing stored procedures, carrying out CRUD operations, querying views, and much more. For instance the following screenshot presents just a small subset of newly generated MySQL REST API endpoints!  

Creating a Role and API Key

All DreamFactory-generated APIs are automatically protected by (at minimum) an API key. You can optionally authenticate users using basic authentication, SSO, or Directory Services (LDAP and Active Directory). Furthermore, you can associate each API key and/or user with a *role* which determines exactly what services the user is allowed to access. Not only that, you can restrict interactions to a specific database table or set of tables, a specific endpoint(s), and even restrict which HTTP methods are allowed. As an example, let’s create a new role which restricts the associated API key to interacting with a single table in a read-only fashion within the newly created MySQL API. To do so, navigate to the Roles tab, and click the Create button. You’ll be presented with the interface found in the below screenshot. In the screenshot you’ll see I’ve already assigned a name and description for the role, and made it active by selecting the Active checkbox.   Next, click the Access tab. This is where you’ll define what the role can do. In the below screenshot you’ll see I’ve limited the role to interacting with the MySQL service, and within that service the role can only interact with the _table/employees* endpoint via the GET method. We’re on lockdown baby!   Save the role by clicking the Save button. Now we’ll create a new API key and associate the key with this role. To do so, click on the Apps tab located at the top of the screen, and then click the Create button. Assign your new App a name and description, ensure it is set to Active, and then assign it the default role of MySQL just as I’ve done in the below screenshot. Regarding the App Location setting, presuming you plan on interacting with the API via a web or mobile application, or via another web service, then you’ll want to select “No storage required”.   Press the Save button and you’ll be returned to the Apps index screen where the new API key can be copied! Copy the key into a text file for later reference.

Configuring CORS

We have one final configuration step before being able to test the API from outside the DreamFactory administration interface. You’ll need to enable CORS (Cross-Origin Resource Sharing) for the new API. For purposes of demonstration, you can set the default CORS setting as I’ve done in the below screenshot, which will allow API-restricted traffic from all network addresses:  

Testing the REST API

With the API generated, API key and associated role created, and CORS configured, you’re ready to begin interacting with the API via a client! I like to use Insomnia for HTTP testing on MacOS, however another popular solution is Postman. In the following screenshot I’m using Insomnia to contact the /api/v2/_table/employees endpoint using a GET request.   Recall that we’ve locked down this API key to only interact with the /api/v2/_table/employees/* endpoints using the GET method. So what happens if we try to POST to this table? A 401 (Unauthorized) status code is returned, as depicted in the following screenshot:   Where to From Here? Believe it or not, we’ve only scratched the surface in terms of what DreamFactory can do for you. If you’d like to see our SQL Server, Oracle, or MongoDB connectors in action, or would like to watch how easy it is to convert a SOAP service to REST without writing any code, why not schedule a demo with our engineering team! Head over to https://www.dreamfactory.com/products and schedule a demo today!

Running DreamFactory as a Docker Container

large_h-dark 

Note: We have updated the instructions here to match our DF-Docker repo instructions.  This will pull the latest GitHub repo now.

DreamFactory can be run as a Docker container, which makes it easier than ever to get the backend for your apps up and running. The DreamFactory Docker image is available on Docker Hub, or you can build your own image from the GitHub repo. Using these two methods, I’ll show you how to use Docker to fire up your own DreamFactory instance in just a few steps. This setup uses MySQL for the system database and Redis for the system cache. The basic idea is that you first start the containers for MySQL and Redis, then a container for DreamFactory which links to the others. 

Continue reading “Running DreamFactory as a Docker Container”

Changing An API Key For One of Your Apps In DreamFactory

So what happens if you make a mistake and expose your admin app api_key or just need to change api_key associated with one of your apps?  We have an easy workaround that doesn’t require you to have to change any of your endpoints or having to recreate an app, etc.  This article shows you how to access all of your app API keys via MySQL or, if you haven’t fully started exploring DreamFactory yet, the default SQLite database.

Continue reading “Changing An API Key For One of Your Apps In DreamFactory”

How To Configure An ELK Stack With DreamFactory

DreamFactory has had support for Logstash since version 2.3 for our Gold Tier version.  Elastic makes some great tools to support very robust logging.  Incorporating Elasticsearch, Logstash and Kibana into your powerful, scalable DreamFactory instance is a no brainer, especially for users who have a lot of data being pushed and pulled through various endpoints.  This will make the lives of your admins so much easier with the amount of detail they can grab to troubleshoot issues. Continue reading “How To Configure An ELK Stack With DreamFactory”

What if Chuck Norris Wanted to Create a Service That Automated APIs?

chuck_facts-467532-edited

Chuck Norris Joke Enthusiasts Trust DreamFactory to Automate  APIs

Thanks to amusing Chuck Norris API database site The Internet Chuck Norris Database, you can have some fun and keep the Chuck Norris jokes flowing.  With the help of DreamFactory and our API automation tools, you will always have life-changing insights making those around you just a bit more intelligent, good looking and successful.  Who doesn’t need to understand such nuggets as:

Contrary to popular belief, the Titanic didn’t hit an iceberg. The ship was off course and ran into Chuck Norris while he was doing the backstroke across the Atlantic.

Continue reading “What if Chuck Norris Wanted to Create a Service That Automated APIs?”

Introducing Alternate User Authentication in DreamFactory 2.11

DreamFactory supports all kinds of authentication schemes out of the box, including traditional native authentication (managing users and passwords in its own database), OAuth 1.0 and OAuth 2.0, as well as OpenID Connect and SAML 2.0. While these options cover most authentication scenarios, there are situations where none of these solutions work. For these cases, DreamFactory 2.11 includes an alternate user authentication feature that allows you to use your own database and user table for DreamFactory user authentication. 

Continue reading “Introducing Alternate User Authentication in DreamFactory 2.11”