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": "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
Available in the PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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 6.0 7.0 SaaS | 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!