Blog postMaking integration simpleSeamless

Making integration simple: all about API calls

In this series of short blog posts, we’ll try to break down some of the engineering principles behind integrations. We’ll use examples from Seamless, but the principles will be universal.

API Calls

What is an API call?

Let’s start with an API and then describe an API call.

An API

An API, application programming interface, is the “public face” of one software application to other applications. One app, Seamless, can reach out to another app, let’s say Autotask, and ask the other app for something. Seamless could be asking Autotask for data, Seamless could be trying to update a record in Autotask, etc.

Typically SaaS vendors publish API guidelines which describe the various things that an external system can ask the application to do. As long as Seamless reaches out to Autotask and asks according to the structures laid out in the Autotask API Reference, Autotask should do what Seamless asks.

An API call

An API call is one instance of Seamless asking Autotask to do something. If Seamless asks Autotask for a Contact record where the Contact ID = 123454, that query is a single API call.

How do API calls relate to the real world of building integrations?

It is not usually as simple as “Please can I have the helpdesk Ticket record where the guy was complaining about his slow laptop”.  In our Autotask example, let’s say we’re keeping Autotask in sync with Dynamics 365 (we do this for a clients such as Verdant, Nexus, Simple Secure Tech and more).

Many records within a system will have relationships with other records. To build a complete picture of the Ticket record, we need to bring the associated information from other records. For the purposes of this explanation, let’s say we’re syncing Company, Contact and Ticket information.

  • A Company record usually stands alone. It will have the details of the Company (name, description, contact details, some segmentation info, etc.).
  • A Contact record is often associated with a Company. It will have the details of the Contact (name, description, contact details, etc.) as well as a reference to the Company that the Contact belongs to. In order to build the entire Contact record, the integration also needs to look up the associated Company.
    • Jon Smith is Sales Director at Smith Enterprises.
      • Jon Smith is the Contact Record and it is associated with the Smith Enterprises Company record.
  • A Ticket record is often associated with a Company and a Contact. It will have details of the ticket (subject, description, source of ticket, prioritisation, etc) as well as who reported the issue and, typically, which Company the reporter belongs to. It is also likely that the ticket is assigned to an Agent.
    • Jon Smith has logged a helpdesk ticket detailing issues with his laptop.
      • “Laptop running slowly” is the helpdesk ticket (although it will identified with a unique system identifier, e.g. “Ticket 2322344”)
      • “Jon Smith” is logged as the ticket reporter
      • “Jon Smith Enterprises” is logged as the Company that the Ticket is associated with
      • “Helpdesk Sam” is the agent that the Ticket has been assigned to

In order to fully construct the Ticket record, Seamless may need to make 4 API calls: (1) retrieve the Ticket itself, (2) the Contact record for ticket reporter, (3) the Company record and (4) the Agent.

It doesn’t always end at 4 API calls. Notes/updates on a Ticket are typically stored on a different database table, and it may require more API calls to retrieve these. The same is often the case for attachments associated with a ticket.

Once the ticket is synced from Autotask into Dynamics, it will also be assigned a Dynamics system identifier. Seamless will recognise that the Ticket has been updated in Dynamics as it has a new Dynamics identifier value. It will then write the updated ticket information back into Autotask, i.e. add the Dynamics identifier into the ticket record on Autotask as a cross-reference. This will take additional API calls – possibly one to look up the ticket and another to update the ticket with the Dynamics identifier.

Quite quickly, syncing a single ticket may add up to 6 or 8 API calls.

It sounds so inefficient, does it have to be?

Well – it is not necessarily inefficient. The first thing to bear in mind is that each application will have a different API call structure. In some cases, we can retrieve a Ticket (and associated data) with a single API call, in some cases not. It is also not necessarily the case that one approach is better than another. It will very much depend on how the underlying application is architected and how the overall API breaks down into granular functions to allow as much flexibility as possible.

Why does it matter?

The million dollar question – why should I care? Often different subscription tiers for SaaS applications will include a limit on the number of API calls that can be made, typically within a specific time frame, e.g. 1000 API calls / hour.

When we’re configuring a Seamless integration, one of the things we look at is how are the APIs for the endpoints structured and how does the app vendor control API calls. We will then try and configure Seamless to, as much as is reasonable, make the most efficient use of the API limits for each app.

API limits for some common Seamless endpoints

Screenshots reflect the API reference at the time of publication.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.