An API integration is the code that allows one system to transfer data to or from another system while using an API (application programming interface) to securely access the system. Some API integrations may only an API on one side of the integration, while others might use two or more APIs.

Devs build API integrations for different reasons, but those integrations generally fall into one of two categories: they are either intended to run inside a company to automate internal business workflows, or they are meant to connect systems from different companies for external data sharing.

Since we work with software companies that need to create native integrations connecting their products to the other systems their customers use, our example will cover an external data sharing scenario – but the concepts apply to internal integrations as well.

We’ll lay out this example as follows:

• Integration business needs (the why)
• Integration technical requirements (the what)
• Integration details for execution (the how)

Integration business needs

For this API integration example, your company provides a SaaS product for monitoring building security. Among other things, your app regularly records temperature and humidity levels from sensors installed at critical points in each of your customers' buildings. Your customer needs an integration to export these temperature and humidity values from your product daily to its building maintenance app (StructManager). The customer will then determine if there are correlations between temperature and humidity levels and unplanned maintenance tickets.

Integration technical requirements

When building an integration, you’ll want to start with the technical requirements. These are the basic questions you’ll need to answer before you begin:

• What data will be transferred? (Data)
• Is this a one-way or two-way integration? (Direction)
• How often will the integration run? (Frequency)
• What APIs will be used? (API)
• What transfer protocols will be used? (Protocol)
• What transport languages will be used? (Language)
• How will auth be handled? (Auth)

Let’s fill out all of these for our API integration example:

• Data. Humidity and temperature records per building for the prior day (24-hr-period).
• Direction. One-way export from your product to StructManager.
• Frequency. Once per day at 7 AM building local time.
• API. Your product uses a SOAP API. StructManager uses a REST API.
• Protocol. Both APIs support HTTP.
• Language. Your product outputs SOAP XML. StructManager accepts JSON as input.
• Auth. Both the SOAP API and REST API use OAuth.

In addition, while the humidity data is provided as percentage points of relative humidity (and is the same in both apps), the temperature data coming from your product uses Celsius, while StructManager is set up to use Fahrenheit. Finally, the temperature and humidity data is collected once per minute by your product, but StructManager only needs to know the values every 15 minutes.

So, for this API integration example, we have two APIs, two data formats, two scales for temperature values, and way more data than required. Sounds like we’ll need to do more than just grab the data from one API and hand it to the other.

Integration details for execution

At 7 AM local time, the integration trigger causes the integration to send a query to your product’s SOAP API requesting the records for the specified customer per building for the last 24 hours. Thankfully, your SOAP API supports OAuth, which is built into the connection string. Once the SOAP API receives the request, it sends back XML via HTTP with all the matching records.

A single record sent from your SaaS product looks something like this:

<environmental>
    <customer_id>AA8312</customer_id>
    <building_id>H265<building_id/>
    <sensor_id>1323</sensor_id>
    <sensor_loc>5W2NAB</sensor_loc>
    <timestamp>10:30</timestamp>
    <temperature>27.3</temperature>
    <humidity>55</humidity>
</environmental>

The integration first performs a data format conversion to translate everything from XML to JSON, giving us the following pattern for a single record.

{
"environmental": {
    "customer_id": "AA8312",
    "building_id": "H265",
    "sensor_id": 1323,
    "sensor_loc": "5W2NAB",
    "timestamp": "10:30",
    "temperature": 27.3,
    "humidity": 55
    }
}

For the sample customer, who has 30 sensors distributed over a single building, the daily export from your SOAP API will include 43,200 records, but the integration only needs to send 2,880 of them to StructManager. As a result, we'll need the integration to filter the 43,200 records and strip out every record that doesn't have timestamp values that match the following patterns: hh:00, hh:15, hh:30, and hh:45. And yes, we could figure out a way to request only these records from the SOAP API in the first place, but it’s cleaner in this case to get the superset of data and go from there.

Once the reduced dataset contains only the records we want to keep, the integration will need to loop over the data once more to convert the temperature values from Celsius to Fahrenheit using a bit of simple math. Our sample data now matches the format StructManager needs to import.

{
"environmental": {
    "customer_id": "AA8312",
    "building_id": "H265",
    "sensor_id": 1323,
    "sensor_loc": "5W2NAB",
    "timestamp": "10:30",
    "temperature": 81.1,
    "humidity": 55
    }
}

At this point, all 2,880 records, encoded in JSON, are wrapped up in an HTTP request for the StructManager REST API. Once again, the integration uses OAuth to connect with the API before submitting the data.

Our API integration example has run successfully and will wait until tomorrow at 7 AM for its next run.

Additional API integration resources

Of course, one example can hardly do justice to a topic as complex as API integrations. With that in mind, here are some resources to help further your understanding of API integration concepts:

• APIs by technology (REST, XML-RPC, SOAP, and GraphQL)
• APIs by access type (private, partner, public, and open)
• Integration transfer protocols and transport languages
• Integration media types (formerly called mime types)
• What goes on in the middle of an integration

It’s all about the tools

APIs are hugely helpful in building data integrations between SaaS products. But having the right tools to work with those APIs is critical. As a software company providing in-app integrations, those tools can be the difference between implementing the bare minimum integrations that meet your customers' needs, and implementing integrations that are so much a part of your SaaS product, that your customers can't tell where your product stops and the integration starts. One of those tools is an embedded integration platform.

Request a demo if you'd like to see how an embedded integration platform can help you build API integrations – or integrations where there's not an API in sight.