Webservices – What is this SOAP or REST thing?


IBM i (or AS400/ iSeries) REST web services are everywhere these days. SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) are both web service communication protocols. SOAP is older was the standard approach to web service interfaces for years. Now dominated by REST, which is simpler, faster, and more comprehensive. REST now represents more than 70% of public webservice APIs

Simple Object Access Protocol (SOAP) and Representational State Transfer (REST) are two different, but similar, ways of talking to Web services out there in Internet Land.

There are two major types of web services:

  • SOAP Web Services: SOAP (Simple Object Access Protocol) is an XML-based protocol for accessing web services. Its interface is described in a machine-processable format called WSDL (Web Service Definition Language) document. A web service is described by using a standard, formal XML notion that provides all necessary details like message format, transport protocols, and location to interact with the web service.
  • REST Web Services: REST (Representational State Transfer) is a style of software architecture. The data format is described by using JSON schema notation, and it requires the use of the HTTP transport protocol.

What is SOAP?

SOAP is the long established and much used standard for webservices. It communicates using XML and was originally designed by Microsoft. If in doubt, SOAP is an easy place to start when looking at webservices, but bear in mind that older does not necessarily mean better.

Simply put, SOAP uses XML and a WSDL specification to handle it’s conversations. When Microsoft originally created the SOAP protocol it was to replace older technologies that didn’t understand the Internet — things like Distributed Component Object Model (DCOM) and Common Object Request Broker Architecture (CORBA). Older technologies use binary messaging to talk to each other but building a layer between applications talking with XML messaging lets different systems easily communicate over the internet.

There are some important differences between SOAP and REST

SOAP is a protocol.REST is an architectural style.
SOAP can’t use REST because it is a protocol.REST can use SOAP web services because it is a concept and can use any protocol like HTTP, SOAP.
SOAP only permits XML.REST permits many different data formats including plain text, HTML, XML, and JSON…
SOAP requires more bandwidth and more resources.REST requires less bandwidth and less resources.
SOAP supports both SMTP and HTTP protocols.REST requires the use of HTTP only.
SOAP is more reliable than REST.REST is less secure than SOAP.
In most cases, SOAP is faster than REST.REST is slower than SOAP.
SOAP defines its own security.RESTful web services inherit security measures from the underlying transport.

What is REST?

REST is the new kid on the block. REST was created to improve on areas that SOAP is a little “clunky”. I like REST because it has some cool features that SOAP doesnt offer (like JSON, CSV interfaces for example) but I’ve also found that SOAP can be easier to use because it doesnt have these options. Saying that, REST is quicker to code with because it doesnt have all the large cumbersome requirements of building long XML strings of data. REST communications are shorter and easier to code than SOAP (arguably).

Ibm i webservices primerREST provides a lighter weight alternative.

Instead of using XML to make a request, REST relies on a simple URL in many cases. In some situations you must provide additional information in special ways, but most Web services using REST rely exclusively on obtaining the needed information using the URL approach. 

REST can use four different HTTP 1.1 verbs (GET, POST, PUT, and DELETE) to perform tasks. Unlike SOAP, REST doesn’t have to use XML to provide the response. You can find REST-based Web services that output the data in Command Separated Value (CSV), JavaScript Object Notation (JSON) and Really Simple Syndication (RSS). 

The point is that you can obtain the output you need in a form that’s easy to parse within the language you need for your application.

If SOAP is more verbose than REST – so why do I say it can be easier to use?

Because the wonderful IBM i Power System has a great integrated webserver (commonly referred to as the #IWS) which handles all the webservice XML & JSON conversions for us… but more on that later.

Should I use REST or SOAP?

Hmmm – the million dollar question.

SOAP is the established player in the world of Web service internet access.

  • More verbose than REST but XML is easy for humans (aka programmers to read)
  • Is only XML-compatible
  • Language, platform, and transport independent (REST requires use of HTTP)
  • SOAP can be used in batch style environments because it uses XML format and not point-to-point
  • The WSDL offers nice error handling and data validation before the XML data even gets to your webservice program
  • XML is easy to use with RPG programs (a big bonus for us RPG ILE Programmers

REST is easier to use because of it’s short form and it requires less programming work.

  • REST has a smaller learning curve than SOAP (JSON is just as easy as XML really)
  • REST handles many data formats such as XML, JSON, CSV, and more
  • Can perform a wide range of HTTP Methods
  • It’s smaller so its faster (SOAP uses XML for messages, REST uses XML or JSON which is a less-verbose message formats)
  • a more modern standard that is growing rapidly


Who wins in the great REST vs SOAP Battle?

Personally – I would recommend start with REST and JSON. Get a feel for it. Play with the Integrated webservice and learn XML but focus on JSON

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}