Asynchronous vs. Synchronous Integration Use Cases

Different integration use cases require different methods to help your users solve problems in your SaaS product. Rarely will a product just have one use case; if you really break down your product, you’ll really have a number of different use cases. Take Google’s search engine as an example:

They have many different use cases they’d like to provide to users, and not every use case will use the same tools and technologies. Indexing websites for Google’s PageRank algorithm requires a different approach than say, returning images of a search.

When it comes to integrations, the same asynchronous vs. synchronous framework needs to be applied, and Paragon provides purpose-built solutions for both. Workflows for reliable long-running, asynchronous use cases and ActionKit for responsive, synchronous use cases.

However, it's not always clear what bucket your integration use case may fall into, which we'll get into in this article.

Just to give a quick recap - regardless of which use case you're building, our platform offers:

1. Fully managed auth

2. Abstractions on top of 3rd-party APIs for useful (but often times complex) operations like getting Notion page contents and getting Google Calendar availability

3. Maintenance of 3rd-party actions, so refactoring logic when APIs change is our job, not yours

Synchronous vs Asynchronous

If you’re in engineering and are familiar with these terms already, feel free to skip this section. If you’re not yet familiar, let’s break down these terms.

• Synchronous - a design pattern where we wait for and expect a response quickly

• Asynchronous - a design pattern where we queue a job to a service and are not waiting on the response immediately

To put it simply, synchronous use cases are ones where timeliness is important, whereas asynchronous use cases are ones where jobs can be time or compute intensive, so it’s more important for the job to be done correctly, rather than quickly.

Let’s go back to our Google search engine example.

When a user hits search or clicks on the images tab, they expect Google to immediately respond with the top results and with images. They don’t want to see a loading screen and wait more than a second. These are synchronous use cases where timeliness is important.

In contrast, Google’s search engine algorithm isn’t constantly updating whenever a website is changed; their SEO analytics are not real-time updated to the second, as it’s expected that web crawling, indexing, and analytics can take a while. Those actions are compute-intensive and can take long periods of time. When a user submits their website to Google, they are made aware that the results may take days.

In general, asynchronous tasks are usually very durable, where the asynchronous service is optimized to keep track of failures and will retry jobs in its task queue. Synchronous jobs are usually not as durable, which is OK, because it's easy to re-initiate the lightweight job. If you search on Google and the page fails to load, you can just refresh and it usually works on the next try.

Synchronous Use Cases with Paragon

Now that we know that synchronous use cases are ones where timeliness is paramount, let’s take a look at some examples.

Responsive User Interaction

When you want a user input to result immediately in a change, whether it’s updating data in your application or a 3rd-party integration, you’ll want to use a synchronous pattern. While it would be ideal for every use case and task to be instantaneous in your application, it’s not realistic.

What non-synchronous user interaction looks like

There are exceptions where user interactions lead to asynchronous use cases instead. Certain use cases (if you remember re-indexing websites for Google’s algorithm) cannot be immediate, and so it’s important to have your product set expectations with the user. Some tasks like hitting “send” in Gmail or Slack are expected to result in immediate action. Other tasks like transcribing a video call cannot be synchronous, so you can employ strategies like sending them a notification when their asynchronous job is completed.

Retrieving Data for your UI

For data that is needed for UI components in your frontend application, a synchronous implementation is best, as users expect applications to be responsive with reasonable load times. In this example, we needed a 3rd-party action to get data from our user’s Notion to subsequently render that data in a filepicker UI.

const [pickerState, setPickerState] = useState<{ pages: any, pickedPage: any }>({ pages: [], pickedPage: {} });

useEffect(() => {
  getNotionPages().then((allPages) => {
    setPickerState((prev) => ({ ...prev, pages: allPages }));
  })
}, []);

const getNotionPages = async () => {
  const response = await fetch("<https://actionkit.useparagon.com/projects/>" + process.env.NEXT_PUBLIC_PARAGON_PROJECT_ID + "/actions", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": "Bearer " + sessionStorage.getItem("jwt") },
    body: JSON.stringify({ action: 'NOTION_SEARCH_PAGES', parameters: {} })
  });
  const body = await response.json();
  return body;
}

AI Agent Tool Calling

For chat interfaces, users expect AI agents to be responsive and give confirmation that an action was complete or use the tool response in its answers. If for any reason the request to the 3rd-party API failed, the user is immediately informed and can try again. For these use cases, a synchronous implementation is perfect.

Paragon’s ActionKit for Synchronous Behavior

Paragon’s ActionKit API should be used in synchronous use cases where timeliness and responsiveness are important. It provides the following benefits for synchronous integrations use cases:

• Can handle extremely high concurrency

• Will return a response (success or error) immediately

For any endpoint ActionKit doesn't yet support, you would use the Connect API. With the Connect API, Paragon still manages authentication with low latency. Your team would just need to have more intimate knowledge with how that API behaves.

GET https://proxy.useparagon.com/projects/><PROJECT_ID>/sdk/proxy/googledrive
	/files/<File_ID>/?alt=media

Authorization: Bearer eyJ...
X-Paragon-Use-Raw-Response: 1

Asynchronous Use Cases

Asynchronous use cases are ones that require reliability and can be long-running in the background, freeing your application up for other processes. Let’s look at some integration use cases where asynchronous jobs are a fit.

Data Ingestion

For a use case where your application needs to access, process, and index all the data in your users’ external system, such as all the records in your customers’ CRMs, all the transcripts from their Zoom, or all the files in their Google Drive (this is similar to many RAG and AI use cases), an asynchronous implementation is necessary. Take the Google Drive example below - you need to get all the files from your users’ Google Drive, which requires you to traverse through many potential subfolders. For an enterprise organization, this could mean ingesting tens of thousands of files - an operation that could take minutes or even hours to complete.

Webhook and CRON based Data Synchronizations

If your application needs to receive webhook messages or run a CRON-triggered job (for example, do X every hour) to stay in-sync with your users’ 3rd-party data, an asynchronous implementation would be the right approach.

Data synchronization may force you to re-index your database or bulk add records, which can be compute-intensive and take long periods of time. Furthermore, because you want your data aligned with the 3rd-party source, it’s important that this job has retries and observability into any failed steps.

The queuing and retry behavior of asynchronous implementations are important in situations such as:

• A user uploads 100 files at once to Google Drive, or bulk updates a thousand CRM records at once

• An error occurs on your API (such as a rate limit) that prevents a request for making it through

When situations like these happen, asynchronous implementations ensure that tasks will process, even when your system doesn’t have the resources to complete all of them at a moment’s notice.

Paragon Workflows for Asynchronous Use Cases

Paragon Workflows are designed for these types of asynchronous use cases where you have long-running, compute-intensive, durable jobs. Paragon Workflows offer:

1. A durable workflow engine with auto-retries if individual steps in a workflow fail

2. The ability to handle large volumes of data with concurrent workers

3. Observability into each step of a workflow

4. The ability to run long background jobs

5. Triggers to listen to 3rd-party webhooks, CRON schedules, and integration-enablement events

6. Workflow steps to define complicated logic such as if-else branching steps, concurrent for-loop steps, and API call steps that can call any API including your own

Reiterating here, Workflows also offer many of the same benefits as ActionKit:

1. Fully managed auth

2. Useful operations like getting Notion page contents and getting Google Calendar availability are provided (these actions are useful abstractions on top of the 3rd-party API)

3. Paragon maintains native 3rd-party actions in Workflows, so refactoring logic when APIs change is our job, not yours

Similar to the Connect API, for actions Workflows doesn't support, you can use an integration-enabled step to hit any 3rd-party endpoint.

Wrapping Up

Paragon doesn't provide a hammer for all of your integration use cases - instead, we've built purpose-built tooling for you to build both asynhronous and synchronous use cases.

• ActionKit - built for synchronous use cases that require timely, responsive actions

• Workflows - built for asynchronous use cases that require long-running, reliable jobs

These tools will enable you to build every integration use case for your SaaS product, all under a single integration platform. If you have any questions about using Paragon and how we may fit in with your product, please don’t hesitate to reach out.