Integration Plumbing: What You Need to Know About Web Services and APIs

11 min read | 05 Sep 2018

API Management, Enterprise Integration, ERP Integration, iPaaS (integration Platform as a Service), NetSuite integration, Partner Program, Salesforce Integration

In a previous post, I talked about the basics of integration, a term used every day in business that many folks don’t understand very well. As part of the post, I offered a simple definition of integration, which I’ll repeat here: An integration is simply moving data from one system to another. When I integrate two systems, they are simply sharing data back and forth.

In any discussion of integration, two other terms usually emerge: APIs (application programming interfaces) and web services. This post addresses these concepts and what they mean in the bigger integration picture.

At my company, Eide Bailly, we work a lot with SalesforceNetSuite and other popular enterprise cloud-based applications. And, often, people say to me, “Salesforce and NetSuite have APIs. Why do I need an integration platform or your integration services? Everyone tells me they are open platforms and easy to integrate.”

APIs and web services are key technologies for integrating applications — to merge two systems so they operate as one. But these approaches only address certain aspects of integration. On their own, they don’t solve enterprise integration challenges — at least not very effectively.

But let’s start by taking a look at how web services and APIs work. From that, I’ll explain how they cannot address most integration needs on their own and what it takes to help them work to their full potential.

Join us at Boomi World 2018 November 5-7 in Las Vegas to learn first-hand from Boomi and its great partners like Eide Bailly about how low-code, cloud-native integration can help your organization address the challenges of hybrid IT. Check out the Boomi World website for more information and register today!

You’ve Got Mail

The term “web service” and “API” are often used almost interchangeably, even though there are some fundamental differences.

All web services are APIs, but not all APIs are web services. A web service is an application that makes itself accessible for communication via the web. APIs are a set of protocols and rules that specify how software components should communicate – and it doesn’t have to be via the web. Today we will only be discussing web APIs.

To explain the way web APIs work, I’m going to use an analogy: the mailbox. Think of a 40-story residential skyscraper. When you walk in the front door, there’s often a big set of mailboxes. I like to think of APIs as those mailboxes.

When you have an API, you’re saying, “I’ve got a mailbox.” When I want to send a letter, the first thing I need to know is the address. Similarly, when I need to connect to a web API, I need the web address. In our analogy, that address gets me to the “building” — the application with which I’m trying to integrate such as Salesforce or NetSuite.

Now that I have an address that takes me to the right building, I’ve got a lot of options in terms of mailboxes. Those mailbox options would represent the different services available in the API I’m trying to work with. Salesforce, for example, has a bunch of different web services that can be called.

So, when I’m working with an API, at the end of the address is the name of the specific web service I need. It’s the equivalent of saying, “Now that I’ve gotten to the building, I’m going to add the apartment number of the person I’m trying to reach to the end of the address.”

Let’s say Jan in accounting (using NetSuite) needs to create an invoice whenever a sale is made in Salesforce. She needs the customer name, address, items sold and the amount of the sale.

I have a web service with Jan’s name at the end of the address. I’m calling to the Jan web service at the NetSuite building. The information that I have from Salesforce goes into Jan’s mailbox, so she can do her job.

But what if you don’t include all the information Jan needs? Like the amount. She can’t create the invoice.

Want to learn more about migrating to the cloud and integrating your hybrid IT infrastructure? Please contact a Dell Boomi integration expert or reach out to Eide Bailly Technology Consulting.

APIs: Not Enough for Enterprise Integration

API documentation lists all the APIs available, what each one does, and the information it — the mailbox — needs. It says: “Here are all the fields that Jan knows what to do with; here’s all the information Jan can take.

These five or ten fields, she absolutely must have. They’re required. If you don’t include this information, she cannot create an invoice. If you want to include some additional information, the API might provide some options for that. So API documentation is critical to making API integrations work.

Why is documentation important? Because if I need to perform certain functions via my integration, I must make sure the application I’m integrating with has the mailboxes (APIs) I need to get the job done.

And that means if you’re going to use an application, you need to ask that vendor very specific questions about the APIs. “Do you have an API (a mailbox) that allows me to do X? And, if you don’t have one, is there a combination of APIs that will work?”

Just “having an API” is not enough.

What’s in a Name?

So, in the example with Jan from accounting, we were looking at putting information into a mailbox. We’ll use another example to explain getting information from a mailbox.

Let’s say, for example, that I need all the information about my job candidates. Bob from HR has all that. I need to get the information from Bob, but I must be specific about what I need. Again, this where documentation comes into play.

“Integrations are the pipes that keep data flowing between systems. Custom coding is the equivalent of using rigid steel pipe. It’s perfect. Until something changes. Then it’s a big deal to fix it.”

And somewhere in the documentation, it will note that to get job candidate information, you need to provide Bob with the first and last name of all the candidates you want to review. So if you put a first and last name in Bob’s mailbox, he’ll use that to search the recruiting database, putting the information that comes back in the mailbox to send back to you.

But the documentation should also say the format in which Bob’s mailbox needs the information. If I’m looking for Nick Mortensen’s information and Bob is expecting first name/last name and you give him last name/first name, you’re not going to get what you need. It’s likely Bob’s search will return nothing, because it’s unlikely there is anyone in the database with the first name “Mortensen.”

Integration: Making the Most of APIs

Salesforce and NetSuite have APIs, so why would you need an integration platform? Well, that’s like saying, “I’ve got a mailbox; you’ve got a mailbox; we should be good.” Yes, theoretically. But how will data get from one mailbox to the other?

How are you going to communicate without a mail person? You need someone or something to take the information from your building, go to the next building, find the right mailbox, and put it in.

That’s the role that Boomi plays. It’s the mail person. It brokers the exchange of information between different mailboxes. And, to complicate things further, companies often speak different languages — or in this case, data formats.

It would be the equivalent of Company A speaking French and Company B speaking Spanish. You need a translator. So, often companies can’t communicate or integrate easily because their mailboxes (APIs) require different data formats.

Dates are a good example. One mailbox uses the date like this: 01-01-2018. But another expects dates to look like this: 2018/01/01. If I send a date in the wrong format, it’s like sending somebody a message in the wrong language. The communication — the integration — fails.

So, Boomi (the mail person) not only brokers the exchange of information but also translates that information. Boomi extracts information from one mailbox (API), transforms it, and loads it to another mailbox (API). That’s the ETL (Extract, Transform, Load) component of Boomi’s integration platform as a service (iPaaS).

Want to learn more about integrating your applications and data? Check out Eide Bailly’s practical how-to workbook, “Guide to Integrating Two Systems.”

Mailboxes Are Always Changing

A “hard-coded” or “custom-coded” integration can be interpreted a lot of ways, but, essentially, it is that someone has coded an integration that says, “This endpoint goes to that endpoint, and they are permitted to exchange this particular information between them.”

But suppose, using the mailbox analogy, the building is remodeled. The mailboxes move and the addresses change. If the integration is written in rigid code, it breaks.

This is essentially what happens when a business process changes. Integrations are rarely static because integrations reflect business processes. And, as a company grows and evolves, processes change.

Integrations are the pipes that keep data flowing between systems. Custom coding is the equivalent of using rigid steel pipe from one mailbox to another. It’s perfect. Until something changes. Then it’s a big deal to fix it. The inflexibility of the pipe causes issues.

Since integrations are always in flux, you either have a developer constantly updating, writing and testing code — cutting and welding pipes. Or you use a low-code environment like Boomi, where you drag-and-drop connections, click a few buttons, and everything’s updated. It’s like having flexible pipe. The process of adapting to change becomes much simpler, faster and less expensive with a low-code platform.

Sometimes your requirements are very specific and that rigidity has its place. But 99 times out of 100, low-code flexibility gives you faster, better and more cost-effective options.

Not sure if your requirements are specific enough for a custom code integration? Start by working with your business team to understand the workflows they are trying to address with integration. And with a low-code tool like Boomi, it’s quick and easy to build out a pilot project to see how it would work and what kind of integration exchanges are required.

If you still are not sure how to address your integration needs, partner with an experienced systems integration expert to help you get off to the right start.

Regardless of how you approach your integration project, keep in mind that APIs and web services are just a part of the integration picture. They can provide a quick stop-gap approach in many cases, but over the long term, they will need a full integration platform to build and manage.

About the author: Nick Mortensen is director of development with Eide Bailly Technology Consulting, a Dell Boomi partner and business advisory firm specializing in the implementation, customization and integration of leading ERP, CRM, and cloud technologies.