Using `PATCH` requests to send content patches based on JSONPatch

FAQs Technical FAQs
,
1

It is now possible to send PATCH requests to the Write API with only a series of minimal patches to apply to existing content. You can do this by only sending these patches in the __patches key of the request body (as JSON). This allows you to modify content remotely without having to upload the entire content data along with the changes.

These patches are like instructions, and the full specification can be found over at http://jsonpatch.com. Essentially a patch item consists on an operation (add/replace/remove), a “path” and a value (unless the operation is remove, then a value is not needed).

Paths are strings composed of slashes and key names (for objects) or indices (for arrays), used to address content within a JSON document.

For example, if we wanted to change the text of the first block, we would use this PATCH request:

$ curl --request PATCH \
  --url 'https://builder.io/api/v1/write/page/your-content-ID?apiKey=YOUR_PUBLIC_API_KEY' \
  --header 'Authorization: Bearer YOUR_PRIVATE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "__patches": [
    {
      "op": "replace",
      "path": "/data/blocks/0/component/options/text"
      "value": "This is now the text of my block"
    }
  ]
}'

To work with block data, you would always need to start with /data/blocks since that’s where they live. Following that we have 0, referring to the first element of the blocks collection (collections are “0-indexed”, which means the first element has index 0, the second has index 1, and so on). At this point we have a block selected, so its text can be changed to using component/options/text, and then we use the value key of the patch to set the new text content.

Let’s say for example, now we want to remove the second block, we would use this PATCH request:

$ curl --request PATCH \
  --url 'https://builder.io/api/v1/write/page/your-content-ID?apiKey=YOUR_PUBLIC_API_KEY' \
  --header 'Authorization: Bearer YOUR_PRIVATE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "__patches": [
    {
      "op": "remove",
      "path": "/data/blocks/1"
    }
  ]
}'

Since we referring to the second block, we use 1 as the index, and there’s no value required, since the operation is remove.

You can of course add elements, for this you would set op to add and use path to specify where in the document to add these elements. To add elements to a collection, you would end the path with 0 to insert at the beginning, and use the special index - to append elements at the end. To know more, just go to http://jsonpatch.com/ to learn all about writing these patches.

Keep in mind that using PATCH this way is very powerful, and it also makes it very easy to modify content or blocks in a way that makes them unusable, since it gives you direct access to everything in your content. It is strongly suggested to first download/inspect the JSON content to get familiar with its structure before attempting to modify it using patches.

Also worth noting that there’s still an overall content size limit in place; so you could still encounter some errors when working with content very close to the size limit, and you send patches that makes the overall size go over it.