Understand API patch mechanism

The Item collection API uses a patch mechanism to modify record data in item collections. 

This guide explains how the patch mechanism works, including path targeting, operation types, update modes, and advanced features like automatic downstream triggers.

Prerequisite knowledge 

• Understanding of item collection concepts.

• Understanding of job types. 

Record hierarchy

Before modifying records with the patch mechanism, understand how they’re structured. Records follow a hierarchical structure. A product record can be standalone (with no variants) or contain variants. 

Product Record (identified by a record identifier)  
└── fields (object of product-level fields)  
└── variants (object, optional)  
    ├── variant record Id 1
    │   └── fields (object of variant-level fields)
    ├── variant record Id 2
    │   └── fields
    └── ...

Structure components

• record ID: Unique identifier for the product (for example, "006").

• fields: Key-value pairs of product-level fields.

• variants (optional): Key-value pairs whose keys are the variant IDs, each mapping to a Variant record, which itself has a fields container.

When you add or replace a product record at the top level (for example, "/product-123"), you inherently add or replace all nested fields and variants as well.

What is the patch mechanism?

The patch mechanism provides a structured way to modify records in an item collection. The patch mechanism uses operations that describe specific changes to records. 

How the patch mechanism works

When you submit a patch, you provide a list of operations and choose an update mode (full or delta). Bloomreach processes the operations in sequence, applying each change to the targeted path in your record structure.

Each operation specifies:

• Path: Where to make the change.

• Operation type: The type of change to make.

• Value: What data to apply.

Combine multiple operations into a single patch to modify different parts of your data atomically. The Item collection API applies patches transactionally. Either all operations in a patch succeed, or none do. This ensures records never end up in a partially modified or indeterminate state.

Anatomy of a patch

Core components

• Path targeting: Specify where to make changes and explore examples. 
• Patch operation types: Understanding add, upsert, and remove.

Application and modes

• Patch update modes: Full vs. delta updates.
• Patch format and delivery: How to send patches.

Advanced features

Automatic success triggers: Triggering items and destination updates.