Skip to content

Latest commit

 

History

History
1188 lines (1072 loc) · 21.9 KB

update.md

File metadata and controls

1188 lines (1072 loc) · 21.9 KB
Raw

Update behavior

Patch rules

::: info 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": "master",
  "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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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.

::: info In the examples below only products values are represented, but usually products also include other information as specified in the standard format. ::: ::: panel-link Don't know what a product value is? Check the product value section :::

Add a product value

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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!"
      }
    ]
  }
}

::: info 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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!"
      }
    ]
  }
}

::: info 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

::: availability versions=1.7,2.x,3.x,4.0,5.0,6.0,7.0,SaaS 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!"
      }
    ]
  }
}

::: info 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

::: availability versions=3.x,4.0,5.0,6.0,7.0,SaaS 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.

::: panel-link Don't know what a reference entity record value is? Check the reference entity record value section :::

Add a reference entity record value

::: availability versions=3.x,4.0,5.0,6.0,7.0,SaaS 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."
      }
    ]
  }
}

::: info 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

::: availability versions=3.x,4.0,5.0,6.0,7.0,SaaS 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."
      }
    ]
  }
}

::: info 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

::: availability versions=3.x,4.0,5.0,6.0,7.0,SaaS 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."
      }
    ]
  }
}

::: info 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

::: availability versions=3.2,4.0,5.0,6.0,7.0,SaaS 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.

::: panel-link Don't know what an asset value is? Check the asset value section :::

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

::: availability versions=3.2,4.0,5.0,6.0,7.0,SaaS 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

::: availability versions=3.2,4.0,5.0,6.0,7.0,SaaS 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."
      }
    ]
  }
}

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