By default, API calls to Vessel are forwarded directly to the downstream integration’s API. This means, for instance, when you make an API call to POST unifications/crm/users/list on a Salesforce connection, Vessel makes a call to your customer’s Salesforce instance using the Salesforce APIs and transforms/unifies the data on the fly before returning it.

​

The Problem

This works great when you don’t need to read a lot of data or make many API calls. But what happens if you want to read your customer’s entire Salesforce instance or you need to make many API reads in rapid succession? You run the risk of exhausting your customer’s rate limits, which can cause your integration to fail among other issues.

​

The Solution

Synced-Caches: With Synced-Caches, Vessel does all the hard work of syncing your customer’s integration data to a database, hosting it, and exposing powerful APIs on top of the data. With synced-caches, you don’t have to worry about exhausting your customer’s rate limits when reading data because you’re always making an API call to a dedicated Vessel database.

Synced-caches are also performant and secure - you choose exactly which objects we sync for every connection so we’re never pulling data you don’t need.

The best part? Most objects stay up to date in real time thanks to webhooks.

Here’s a diagram to help illustrate

​

When to turn on Synced-Caching

Why might you want to turn on synced caching?

​

Pros

• Synced Caches don’t come with any read rate limits
  • This supports read heavy workflows, like analyzing all contacts in your customers CRM.
• Synced objects come with two-way associations
  • E.g., Every Task has a dealId and every Deal has a taskId
  • Note: You must sync both objects for two-way associations to work. If you just sync Deals and not Tasks, you may not see the taskId field on Deals.
• Objects that have been synced to the cache also support more powerful filters
  • E.g., you can filter for all contacts that have last names starting with ‘Smi’.

​

Cons

• Syncs run every hour, so the cache data can be out of sync by up to an hour if the downstream system doesn’t have good webhook support.
  • Note: When you use the Vessel API to create or update an object, we will also update the cache. This means only updates that happen outside of our API (such as in the downstream system UI) will be delayed.
• Vessel currently supports syncing most data to the cache with the expection of data returned by the /details endpoints.

In summary, if you want to forgo issues with rate-limits, or want access to powerful features like filtering, synced-caches are an excellent tool to use. However, if your product is sensistive to data being out of sync by up to an hour, you may want to consider making direct API calls instead.

​

How To Use

Here’s how you can start using synced caches to deliver more robust integrations.

​

Setting up a Synced-Cache

The first step is to configure a connection to sync objects to the cache. This configuration is declared when the connection is created at the session-token step. If you want to use synced-cache for an object, you must configure it here.

Here’s an example that configures syncing accounts and deals for a CRM connection.

const sessionToken = await vessel.auth.sessions.create({
	integrationId: "id_of_integration" // must be provided
	connection: {
		sync: {
			objects: { // the objects to sync
				accounts: true, // sync accounts
				deals: true    // sync deals
			}
		}
	}
})

When a connection is created with this configuration, Vessel will immediately start syncing data. Data is streamed, so it will become available through the API as soon as we pull it. This means you can start using the APIs right away, they will just return a limited subset of the data.

If you want to wait for all data to finish syncing before making API calls you have two options:

1. Set up a Webhook

You can set up a webhook and receive a system.sync.initial.complete event when we’ve pulled all of the data.

2. Poll the Connections endpoint

You can reference the connections list endpoint and check the syncState field. When the syncState is initial-sync-complete, we’ve finished syncing all of the data.

{
	"connections": [{
		...,
		// For connections with synced cache enabled only.
        // When syncState is "initial-sync-in-progress", we're syncing the
		// data for the first time. When it's "initial-sync-complete",
		// we've successfully synced all of the data.
		"syncState": "initial-sync-in-progress" // or "initial-sync-complete"
	}]
}

​

Making API Calls

After you’ve configured a connection to use the synced-cache, you must set the synced flag to true when making an API call to hit the cache.

// Makes a request to the synced-cache
// Make sure deals is set to true in the sync config when creating the connection.
const deals = await vessel.unifications.crm.deals.list({
  synced: true,
});

// Makes a request directly to the downstream integration
const deals = await vessel.unifications.crm.deals.list();

If synced is not set, then a direct API call to the downstream platform will be made instead. If synced is set and you did not configure the connection to sync the object you are accessing, then an error will be thrown.