In our new blog article series, we will dive into the topic of IT systems integration. We will begin by describing integration concepts for anyone who isn’t yet experienced with integrations. Later on, we will present more advanced concepts.

Today’s topic will shortly and simply explain the integrations concept and look into what SOAP and REST are and what the differences are between them. The articles will be written mostly from the ServiceNow perspective and provide examples based on SN functionalities. 

Integration – what is that?

What is an integration? By definition, IT integration is the process of connecting a couple of different IT systems or applications together so that they can work in coordination to exchange data with each other to provide improved functionality. A simple everyday example of an integration is when a company’s website displays a Google Maps plugin on its page, helping you locate their business. The website integrates functionality provided by Google Maps by connecting to Google APIs and pulling all the data from their side.

What is an API? Great question! Application Programming Interface is a programmatical entry point to an application or a server, that allows you to perform certain operations on that system which are permitted by the said system. In other words, to make it simple (for now, we will get into details later), let’s assume it is kind of like a USB port – if you plug a USB device into it, it permits you to perform certain functions on your machine. APIs are similar, except you are the device 😉

Why do we need integrations? Well, sometimes you want to display data from one system in the other system (e.g. Google maps plugin on your website), sometimes you want to make the system contain the same parts of data at all times (e.g. feed your user account information from Active Directory). Anytime you need two different systems to talk with each other in any way, you are thinking of integrations.

How do we make systems communicate? You need to exchange the data between them somehow. For this, you will need a communication protocol from one system to the other and decide how you want to access the data. The most popular protocol nowadays is HTTP – yes, your systems talk to each other using the same protocol that you use to browse webpages. Then, there is the way you access the data – sometimes you will have one system push the data to the other, and sometimes one will expose its data for grabs whenever the other system wants to pull it.

That sums up the very basics that we need to get started.

SOAP vs REST

You have your systems, you have the protocol, and now you want to make them talk to each other. How are you going to do it? Like in a real language, you need some sort of rules to make sure both systems can understand each other. This is where messaging protocols come into play. It defines how the systems can communicate. 

SOAP (Simple Object Access Protocol) is an example of a messaging protocol. It communicates via HTTP (among other protocols), and utilizes XML as the data format, it has an envelope which is a sort of packaging that for the message to follow the required structure and data gets encoded into the envelope. 

Once SOAP API is published, it generates WSDL (Web Services Description Language) which outlines every available operation (function if you will) that can be performed along with the data required to run it. 

Here is an example of a SOAP request envelope, that has a nicely packaged pull request to obtain information about a stock price by providing the name of the stock:

SOAP was widely used in corporate integrations a couple of years back, due to its structure & predictability – each web service is supposed to perform a particular task in a particular manner. This works well when you have straightforward operations to perform between systems at defined times.

You can use SoapUI by SmartBear to work with SOAP requests through a desktop client.

REST is an architectural style rather than a messaging protocol. It means REpresentational State Transfer and provides principles and constraints on how to maintain your API communication to make it RESTful. And what does it mean to be RESTful? It means that:

• your interface has a strict set of methods used to exchange data (GET/PUT/PATCH/POST/DELETE)
• the same request should always return the same result
• your API informs you of the result of your operation
• API call should precisely tell you what it is trying to obtain
• The client never interacts with the server data directly
• API enables caching

The above example is a successful GET request (=GET me the data) to obtain product data and it returns 3 products. If any other user sent the same request as the one above (having access to this API) then that user would also receive 3 products back. If I wanted to change a product, I could send a PUT request, which the API would process and trigger changes on the server. Note that I did not provide any payload in this GET transaction – I only sent the request as GET to the provided endpoint and it returned the data that the endpoint is supposed to return. See? RESTful!

Any API that fits REST rules is called REST API. The most popular way of communicating via REST APIs is through JSONs, which are Javascript Object Notations, a widely used format for passing the data between web apps.

The most popular app to work with REST API calls is Postman.

SOAP vs REST

We have an example of a SOAP API request and an example of a REST API request. They do look quite different, right? Putting that into words, what are the main differences between them? 

• REST requests are lighter than SOAP
• Thus (among other reasons) REST is easier to learn
• SOAP has standardized requests from a technical standpoint, REST only follows general principles
• SOAP can only use XML payloads, while REST can have a couple of different formats
• REST follows modern standards, while SOAP is a bit ‘old-school’ nowadays
• This makes SOAP better to work with big cumbersome legacy systems that require standardized structure, but nowadays a lot of systems utilize REST APIs
• REST is cheaper to build – you only need a web server to build your integration! 

This should give you a decent outlook on what is going on with each of those the next time you get to work with them. 

Summary

The above article should bring you a little closer to what SOAP and REST APIs are. This just yet may not be enough to get you independent in building your first API with one of those, but it should give you a good understanding of their concepts if you stumble onto the integrations topic somehow. I encourage everyone to download SoapUI and Postman software and try to play around a little bit with both requests to cement the knowledge. Next time, we will look into how to build example APIs in ServiceNow. Until then, keep on coding!

Link to relevant blog articles: 
The Low-Risk Approach to a Successful VA Implementation

ServiceNow is the perfect companion for Microsoft Teams