The sync API allows you to keep a local copy of all content of a space up to date via delta updates. This tutorial will show you how to use the Sync API with the Contentful JavaScript SDK.

This tutorial shows some examples using the localStorage API on a browser, but you can also use any other storage wrapper or any storage layer in Node.js.

Getting started

After you've installed the SDK you'll need to setup the client with your credentials:

var client = contentful.createClient({
  space: 'cfexampleapi',
  accessToken: 'b4c0n73n7fu1'
})

Now you can run your first sync:

client.sync({initial: true})
.then((response) => {
  console.log(response.entries)
  console.log(response.assets)
})

As this is the first sync, your response will contain all existing entries and assets.

Any links from entries to other entries and assets will also be resolved. If you don't want that to happen, you can turn it off:

client.sync({
  initial: true,
  resolveLinks: false
})
.then((response) => {
  console.log(response.entries)
  console.log(response.assets)
})

If you'd like to store the retrieved content, you can use the convenient toPlainObject method or stringifySafe to prevent issues with circular links, for example:

client.sync({initial: true})
.then((response) => {
   const responseObj = JSON.parse(response.stringifySafe());
   const entries = responseObj.entries;
   window.localStorage.setItem('contentfulEntries', JSON.stringify(entries))
})

Your response will also contain a token, which you should store:

client.sync({initial: true})
.then((response) => {
  window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken)
})

Continuing the sync

The next time you want to get updated content, you can use the token you previously stored. This will give you only new, and updated content, as well as a list of what content has been deleted:

client.sync({nextSyncToken: window.localStorage.getItem('contentfulSyncToken')})
.then((response) => {
  console.log(response.entries)
  console.log(response.assets)
  console.log(response.deletedEntries)
  console.log(response.deletedAssets)
  // store the new token
  window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken)
})

Every time you perform a sync you get a new token, which represents that point in time for your space, so don't forget to store it again.

You can then loop through the content you have previously stored and removed any content that is now marked as deleted, but that is left as an exercise to the reader.

Limiting the number of updates per request

By default the Sync API will return 100 updates per request. However, this may result in a maximum size limit being reached if your changed content is too large. If this happens, you can add a limit to the number of entries to return per request on the initial call.

client.sync({
  initial: true,
  limit: 10
})
.then((response) => {
  console.log(response.entries)
  console.log(response.assets)
})

Notes

• You can only specify the limit on the initial sync
• Do not pass limit on subsequent calls. The returned sync token will already have the initial limit embedded
• The maximum value for limit is 100
• The limit parameter requires contentful.js >= 7.14.0

Conclusion

Using the Sync API, you can keep your users easily up to date with your latest content.

You can find the JavaScript SDK on Github. Don't forget to open an issue if you run into any trouble.