How to use the Public API sync

This article explains how sync data to the Public API using the sync API.

Using the new papi-sync API

Syncing products using the API requires three steps. 

1. Create session
2. Add products
3. Finish the session and start the sync

We use a session to batch the products and increase performance. Starting one session per product is not recommended.

Only one sync can run at any time and additional sync sessions will be queued.

1. Create session

Example request body

Specify one or more contexts to sync. Products added will be synced in all specified contexts. 

{
  "contexts": [
    "en"
  ]
}

Response

If successful, this will result in a '200 - OK' response.

The response headers will include a Resource-Id containing the GUID of the newly created sync session. 

Try it in readme.io

2. Add products

Use the GUID from the previous step as the {id} in the request to add products to the sync session.

Example request body

This request adds two products to the sync session:

{
  "products": [
    {
      "productId": "659ea8f7cd619c778f88a7a4",
      "lastUpdate": 1705073128120
    },
    {
      "productId": "659eac3b4a61902524db1d2c",
      "lastUpdate": 1705073128120    
    }
  ]
}

The lastUpdate timestamp ensures that a product is not synced if it changes between being added and synced.

Before syncing, the system compares the timestamp in the sync session with the timestamp of the product in PIM. If the product in PIM has a newer timestamp, that specific product will fail to sync. If the timestamp matches or is older, the product sync succeeds.

The timestamp should typically be set to the moment the sync session starts.

If lastUpdate is omitted, the product will be synced regardless of any changes made in PIM.

Response

If successful, this will result in a '200 - OK' response.

If the request fails with a '400 - Bad request', none of the products in the request will be added to the sync. The error message will contain information about which products could not be added to the session.

Try it in readme.io

3. Finish the session and start the sync 

Use the GUID from step 1 as the {id} in the request to close the sync session and start the sync. This can only be done once for a sync session. This will start the asynchronous sync job to copy the products from PIM to PAPI.

Example request body

No request body

Response

If successful, this will result in a '200 - OK' response.

Try it in readme.io

Migrating from old to new sync

To perform a sync in the old bluestone-sync service, the first step was to generate a sync report for all products that were changed in the organization. This was a time consuming process. After the sync report had been generated it could take a lot of time to actually sync the products.

In the new bluestone-papi-sync service, there is no upfront report. It will sync a selection of specific products and it will be much faster than the old one.

Depending on which version of the sync an organization is using, different API endpoints must be used to change product states.

APIs for Changing Product States (Old Sync)

The following PIM API endpoints support only the old sync:

• Change product states by IDs:
  POST /products/states/by-ids

• Change product state (specific action):
  POST /products/{id}/{action}

APIs for Changing Product States (New PAPI Sync)

For organizations using the new PAPI Sync, the following endpoints should be used instead:

Publishing and Unpublishing Products

• PAPI Sync API
  POST /product/state/list/by-ids
  Actions: PUBLISH, UNPUBLISH

Archiving and Unarchiving Products

• PIM API
  PUT /products/archive/by-ids
PUT /products/unarchive/by-ids