APIs can be extremely powerful and form the backbone of the web across varying types of online applications.
Today we’ll dive into detail around the available types of web-based APIs.
First, a quick recap on APIs:
- API stands for Application Programming Interface.
An API is a collection of programming tools, rules, and documentation that allows data to be moved from one place on the web to another.
Sites that contain static content like personal blogs and marketing landing pages may never have a need to expose an API, because it’s not necessary to programmatically transfer data to and from these applications.
Larger sites that handle more complex and dynamic data, like Expedia or PayPal, need an interface to distribute and collect data.
For instance, when Expedia displays the cheapest flights from different airline providers they pull data from APIs so that you do not have to go off-site to retrieve the best prices.
APIs are also used as the foundation on top of which a website or application is built. This is known as API-First Development, which helps developers to easily build sites and apps around a consistent baseline API.
There are two major API standards that we’ll look at in-depth today: SOAP and REST.
The Major Players: SOAP and REST
- SOAP originally stood for Simple Object Access Protocol. (Now, simply “SOAP”).
- REST stands for REpresentational State Transfer.
SOAP and REST have both been around for over a decade, yet there are still many misconceptions surrounding the debate between them.
Some experts argue that comparing these two types of APIs is like comparing apples to oranges. They emphasize that SOAP is a protocol and REST is an architectural style.
For our purposes we’ll treat them as types of APIs, drawing out what it means for one to be a protocol and the other to be an architectural style.
SOAP as a Protocol
SOAP was developed by Microsoft in 1998 as a way for remote machines to talk to each other in a standard, coherent manner over the web.
The major problem faced by engineers at the time was that the internet hosts an array of different types of machines running different hardware and operating systems, such as UNIX-style servers versus Windows servers.
To get around this incompatibility, the SOAP protocol defined a strict standard of communication which uses a common data format (XML) easily processed by mutually-incompatible machines.
A SOAP-based API works by sending data in bundles of XML files and moving them along the HTTP protocol, allowing easy conversation through the use of a shared language and acting as a “social contract” for web applications.
Protocols like SOAP are the cornerstone of what makes the web work, but as with most technologies, things have evolved quickly since 1998.
Which brings us to REST…
REST as an Architectural Style
Two years after SOAP was introduced, a computer scientist, Roy Fielding, noted that the general workings of HTTP afforded a means to do more than send and receive HTML pages.
That is, HTTP can also be used to efficiently process data across web applications and within webpages; and not only serve human-readable webpages to a web browser.
Using the standard HTTP request methods like GET, POST, PUT, DELETE along with URIs to identify the data’s location on another web server, one can easily transfer data between clients, servers, and external web applications with no extra protocols required.
With a REST API, data can be represented as JSON and accessed by requesting a URL containing instructions about the data to return in the response.
REST describes how developers can use the existing URL-based HTTP architecture in a clever way to facilitate communication between computers.
Some view this as a hack in contrast with SOAP’s strict nature as a protocol, but REST has become a largely popular choice for developers building APIs for their web apps.
Pros, Cons, and Caveats
Why use SOAP?
Because of the popularity of RESTful APIs, SOAP is sometimes viewed as a legacy technology. There are still cases where it makes sense to implement SOAP:
- Standardization: With defined rules and specs, developers are able to reference best practices for their APIs and be sure about what their code does.
- Enterprise-friendly: Designed for the enterprise, supporting ACID-compliant transactions and two-phase commits across distributed transactional resources.
- Built-in Extensibility: Extensions like WS-ReliableMessaging and WS-Security help protect the consistency of data and ensure end-to-end security. REST has no such built-in functionality.
- Transport Layer Independence: Unlike REST which is HTTP/HTTPS-only, SOAP can be sent over HTTP/HTTPS, SNMP, TCP, UDP, JMS, or XMPP.
- Error Handling: SOAP’s XML error metadata allows fault-checking and automation of error handling.
Who uses SOAP?
The majority of organizations using SOAP are in the enterprise arena, including banks, billing companies, and payment gateways like PayPal. This is mainly due to SOAP’s security advantages over REST.
With the ubiquity and advancement of REST technology, some age-old SOAP providers like PayPal are offering both types.
Why use REST?
REST APIs are becoming increasingly popular on the web. Right now over 70% of public APIs rely on REST.
Here are a few reasons why:
- Easy to use: Quick setup and documentation is easy to create and maintain.
- Performance: Unlike with SOAP, REST data can be easily cached. Combined with lower message overhead (lightweight JSON vs. hefty XML), you get a faster, lower bandwidth API, especially for mobile applications.
- Scalability: REST is extremely flexible and can be swiftly adapted to suit the needs of expanding operations.
- Multiple Data Formats: Output data is not restricted to XML. Can be JSON, CSV, XML, etc.
- Plays well with JavaScript: REST integrates well with JavaScript, which allows easy building of dynamic APIs using tools such as Node.js.
Who uses REST?
Most of the tech giants and social networks today use a form of RESTful API over SOAP. The list includes:
- Google (Example: Gmail API)
- Facebook (Facebook’s Graph API is based on REST)
- Yahoo
- Amazon
… And the list goes on.
Nowadays, more and more companies are deprecating their use of SOAP in favor of a REST API. Despite this, there will still be a niche for SOAP for years to come.
Our conclusion? If enterprise-level security and consistency across internal distributed resources aren’t your top priorities, look to REST.