Application Programming Interface
In the simplest of terms, an API is a piece of software that plugs one application directly
into the data and services of another by granting it access to specific parts of a server. APIs
let two pieces of software communicate, and they’re the basis for most modern
applications. They allow us to streamline IT architectures, automate marketing workflows,
and make it easier to share data sets.
REST API
REST (Representational State Transfer) is truly a “web services” API. REST APIs are
based on URIs (Uniform Resource Identifier, of which a URL is a specific type) and the
HTTP protocol and use JSON for a data format, which is super browser -compatible. (It
could also theoretically use the SOAP protocol, as we mentioned above.) REST APIs can
be simple to build and scale, but they can also be massive and complicated—it’s all in how
they’re built, added on to, and what they’re designed to do.
REST properties:
REST is all about simplicity, thanks to HTTP protocols.
REST APIs facilitate client-server communications and architectures. If it’s
RESTful, it’s built on this client-server principle, with round trips between the
two passing payloads of information.
REST APIs use a single uniform interface. This simplifies how applications
interact with the API by requiring they all interface in the same way, through the
same portal. This has advantages and disadvantages; check with your developer to
see if this will affect implementation changes down the road.
REST is optimized for the web. Using JSON as its data format makes it
compatible with browsers.
REST is known for excellent performance and scalability. But, like any
technology, it can get bogged down or bog down your app. That’s why languages
like GraphQL have come along to address problems even REST can’t solve.
SOAP
SOAP (Simple Object Access Protocol) is its own protocol and is a bit more complex by
defining more standards than REST—things like security and how messages are sent.
These built-in standards do carry a bit more overhead. Still, they can be a deciding factor
for organizations that require more comprehensive features in the way of security,
transactions, and ACID (Atomicity, Consistency, Isolation, Durability) compliance. For the
sake of this comparison, we should point out that many of the reasons why SOAP is a good
choice rarely apply to web services scenarios, which makes it more ideal for enterprise -
type situations.
SOAP Properties:
SOAP has much tighter security. In addition to SSL support, WS-Security is a
built-in standard that gives SOAP some more enterprise-level security features if
you require them.
Successful/retry logic for reliable messaging functionality. REST doesn’t have a
standard messaging system and can only address communication failures by
retrying. SOAP has successful/retry logic built-in and provides end-to-end
reliability even through SOAP intermediaries.
SOAP has built-in ACID compliance. ACID compliance reduces anomalies and
protects the integrity of a database by prescribing how transactions can interact
with the database. ACID is more conservative than other data consistency models,
which is why it’s typically favored when handling financial or otherwise sensitive
transactions.
SOAP vs. REST example
To better grasp the practical differences between SOAP and REST, we have created an
example of how the same operation could be performed using the two technologies. In the
example, we are making a request for user details.
SOAP example
Using SOAP, the request to the API is an HTTP POST request with an XML request body.
The request body consists of an envelope which is a type of SOAP wrapper that identifies
the requested API, and a SOAP body that holds the request parameters. In this case , we
want to fetch the user with the name “John.”
<soapenv:Envelope xmlns:soapenv="[Link]
xmlns:sch="[Link]
<soapenv:Header/>
<soapenv:Body>
<sch:UserDetailsRequest>
<sch:name>John</sch:name>
</sch:UserDetailsRequest>
</soapenv:Body>
</soapenv:Envelope>
The response, just like the request, consists of a SOAP envelope and a SOAP body. In this
case, the SOAP body represents the requested user data.
REST example
REST APIs can be called with all of the HTTP verbs. To get a resource, in this case, a user,
a GET request is used. While the SOAP request holds the user’s name in the body, a REST
API accepts GET parameters from the URI.
GET [Link]
As mentioned, REST APIs typically use the data format JSON. The user is represented in
JSON like this:
SOAP vs. REST: The key differences
SOAP is a protocol, whereas REST is an architectural style
An API is designed to expose certain aspects of an application’s business logic on a server,
and SOAP uses a service interface to do this while REST uses URIs. While SOAP APIs are
designed after the functions that the API exposes, REST APIs are designed after the data.
For example, a SOAP API that exposes functionality to create a user might include a
function called "CreateUser" that would be specified in the SOAP body. A REST API
would instead expose a URL /users, and a POST request towards that URL would create a
user.
REST APIs access a resource for data (a URI); SOAP APIs perform an operation
REST is an architecture that’s more data-driven, while SOAP is a standardized protocol for
transferring structured information that’s more function-driven. REST permits many
different data formats, including plain text, HTML, XML, and JSON, which is a grea t fit
for data and yields more browser compatibility; SOAP only uses XML. SOAP APIs are
limited to using XML and the format including the SOAP envelope, header, and body, as
we saw in the example above. REST APIs are, however, format agnostic. While the mo st
common format is JSON, formats such as XML, plain text, and XML are also valid for
REST APIs.
Security is handled differently
SOAP supports WS-Security, which is great at the transport level and a bit more
comprehensive than SSL, and more ideal for integration with enterprise-level security
tools. Both support SSL for end-to-end security and REST can use the secure version of the
HTTP protocol, HTTPS. While both SOAP and REST APIs can encrypt their
communication using HTTPS and SSL, the additional layer of WS-Security provided by
SOAP acts on the message level to make sure not only that the content of a message can be
read by the right server but also the right process on the server.
SOAP requires more bandwidth, whereas REST requires fewer resources (depending on the
API)
There’s a little more overhead with SOAP out of the gate because of the envelope -style of
payload transport. Because REST is used primarily for web services, its being lightweight
is an advantage in those scenarios.
As you can see in the example SOAP request in the previous section, a SOAP request
contains more data than a REST request. This means more bandwidth will be consumed
when communicating with a SOAP API. This can have an impact on systems with large
amounts of traffic.