The REST API basics

#Update behavior

#Patch rules

In accordance with JSON definition, what is called object in this documentation is a data structure indexed by alphanumeric keys, arrays don't have any key.

A PATCH request updates only the specified keys according to the following rules:

  • Rule 1: If the value is an object, it will be merged with the old value.
  • Rule 2: If the value is not an object, it will replace the old value.
  • Rule 3: For non-scalar values (objects and arrays) data types must match.
  • Rule 4: Any data in non specified properties will be left untouched.

#Rule 1: Object update

If the value is an object, it will be merged with the old value.

#Example

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
      "labels": {
        "de_DE": "Stiefel"
      }
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes",
        "de_DE": "Stiefel"
      }
    }
    

#Rule 2: Non object update

If the value is not an object, it will replace the old value.

#First example

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
      "parent": "clothes"
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "clothes",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

#Second example

Original resource

{
      "identifier": "boots-4846",
      "categories": ["shoes", "boots"]
    }
    

PATCH request body

{
      "categories": ["boots"]
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "categories": ["boots"]
    }
    

#Rule 3: Validation on data types

For non-scalar values (objects and arrays) data types must match.

#Example

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
      "labels": null
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "clothes",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

Nothing has changed and a 422 error is returned.

HTTP/1.1 422 Unprocessable entity
    
    {
      "code": 422,
      "message": "Property `labels` expects an array as data, `NULL` given. Check the standard format documentation."
    }
    

#Rule 4: Non specified properties

Any data in non specified properties will be left untouched.

#Example

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

#Concrete use cases

#Move a category

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

You want to move the boot category from the category master to the category shoes. Here is how you can achieve it.

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
      "parent": "shoes"
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "shoes",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

#Modify a category label

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

For the locale fr_FR, you want to change the label of the category boots from Bottes to Bottines. Here is how you can achieve it.

Original resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottes"
      }
    }
    

PATCH request body

{
      "labels": {
        "fr_FR": "Bottines"
      }
    }
    

Resulting resource

{
      "code": "boots",
      "parent": "master",
      "labels": {
        "en_US": "Boots",
        "fr_FR": "Bottines"
      }
    }
    

#Place a product in a new category

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

You want to place the product boots-4846 in the new category winter_collection. Here is how you can achieve it.

Original resource

{
      "identifier": "boots-4846",
      "categories": ["shoes", "boots"]
    }
    

PATCH request body

{
      "categories": ["shoes", "boots", "winter_collection"]
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "categories": ["shoes", "boots", "winter_collection"]
    }
    

#Remove a product from a category

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

You want to remove the product boots-4846 from the category boots. Here is how you can achieve it.

Original resource

{
      "identifier": "boots-4846",
      "categories": ["shoes", "boots"]
    }
    

PATCH request body

{
      "categories": ["shoes"]
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "categories": ["shoes"]
    }
    

#Update product values

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

The PATCH behavior described above is quite intuitive. However, applying a PATCH containing product values on a product is a bit different.

In the examples below only products values are represented, but usually products also include other information as specified in the standard format.

#Add a product value

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

You want to add the description of the product boots-4846 for the en_US locale.

Original resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Mug"
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Mug"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

Wondering how to format the data property in these product values? In fact, it depends on the attribute type. More details right here!

#Modify a product value

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

#First example

You want to modify the name of the product boots-4846 for the en_US locale.

Original resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Mug"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Incredible mug"
          }
        ]
      }
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Incredible mug"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

#Second example

You want to modify the name of the product boots-4846 for the fr_FR locale but the name on the en_US locale is already set.

Original resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Incredible mug"
          },
          {
            "locale": "fr_FR",
            "scope": null,
            "data": "Tasse"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "name": [
          {
            "locale": "fr_FR",
            "scope": null,
            "data": "Tasse extraordinaire"
          }
        ]
      }
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Incredible mug"
          },
          {
            "locale": "fr_FR",
            "scope": null,
            "data": "Tasse extraordinaire"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

Wondering how to format the data property in these product values? In fact, it depends on the attribute type. More details right here!

#Erase a product value

Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: CE EE

You want to erase the name of the product boots-4846 for the en_US locale.

Original resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Incredible mug"
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": null
          }
        ]
      }
    }
    

Resulting resource

{
      "identifier": "boots-4846",
      "values": {
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": null
          }
        ],
        "short_description": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "This mug is a must-have!"
          }
        ]
      }
    }
    

Wondering how to format the data property in these product values? In fact, it depends on the attribute type. More details right here!

#Update reference entity record values

Available in the PIM versions: 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: EE

Applying a PATCH on a reference entity record containing values is also a bit different. Below we present three use cases to update these reference entity record values.

#Add a reference entity record value

Available in the PIM versions: 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: EE

You want to add the short_description of the reference entity record kartell for the en_US locale.

Original resource

{
      "code": "kartell",
      "values": {
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "The famous Italian brand"
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "The famous Italian brand"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

Wondering how to format the data property in these reference entity record values? In fact, it depends on the attribute type. More details right here!

#Modify a reference entity record value

Available in the PIM versions: 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: EE

#First example

You want to modify the short_description of the kartell reference entity record for the en_US locale.

Original resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "The famous Italian brand"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "A well-known manufacturer of high-end furniture"
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "A well-known manufacturer of high-end furniture"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

#Second example

You want to modify the short_description of the kartell reference entity record for the fr_FR locale but the short_description on the en_US locale is already set.

Original resource

{
      "identifier": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "A well-known manufacturer of high-end furniture"
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Kartell, éditeur de meubles"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "short_description": [
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "L'éditeur italien de meubles de haute qualité"
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "A well-known manufacturer of high-end furniture"
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "L'éditeur italien de meubles de haute qualité"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

Wondering how to format the data property in these reference entity record values? In fact, it depends on the attribute type. More details right here!

#Erase a reference entity record value

Available in the PIM versions: 3.x 4.0 5.0 Serenity  |  Available in the PIM editions: EE

You want to erase the short_description of the kartell reference entity record for the en_US locale.

Original resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "A well-known manufacturer of high-end furniture"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": null
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "kartell",
      "values": {
        "short_description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": null
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell was founded in 1949 in Italy. Today, it's a well-known brand that sells high-end furniture."
          }
        ]
      }
    }
    

Wondering how to format the data property in these reference entity record values? In fact, it depends on the attribute type. More details right here!

#Update asset values

Available in the PIM versions: 3.2 4.0 5.0 Serenity  |  Available in the PIM editions: EE

Applying a PATCH on an asset containing values is also a bit different. Below we present three use cases to update these asset values.

#Add an asset value

You want to add the warning_message of the allie_jean_picture asset for the en_US locale and mobile channel.

Original resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Allie jean, blue"
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Retouched photo."
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Allie jean, blue"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Retouched photo."
          }
        ]
      }
    }
    

#Modify an asset value

Available in the PIM versions: 3.2 4.0 5.0 Serenity  |  Available in the PIM editions: EE

#First example

You want to modify the warning_message of the allie_jean_picture asset for the en_US locale and the mobile channel.

Original resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Allie jean, blue"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Retouched photo."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Allie jean, blue"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

#Second example

You want to modify the alt_tag of the allie_jean_picture asset for the fr_FR locale but the alt_tag on the en_US locale is already set.

Original resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Allie jean, blue"
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Veste Amor, bleu"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "alt_tag": [
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Jean Allie, bleu"
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Amor jacket, blue"
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Jean Allie, bleu"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

#Erase an asset value

Available in the PIM versions: 3.2 4.0 5.0 Serenity  |  Available in the PIM editions: EE

You want to erase the alt_tag of the allie_jean_picture asset for the en_US locale.

Original resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Amor jacket, blue"
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Jean Allie, bleu"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

PATCH request body

{
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": null
          }
        ]
      }
    }
    

Resulting resource

{
      "code": "allie_jean_picture",
      "values": {
        "alt_tag": [
          {
            "locale": "en_US",
            "channel": null,
            "data": null
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Jean Allie, bleu"
          }
        ],
        "warning_message": [
          {
            "locale": "en_US",
            "channel": "mobile",
            "data": "Not retouched photo."
          }
        ]
      }
    }
    

Wondering how to format the data property in these asset values? In fact, it depends on the attribute type. More details right here!