Management API: Add document patch endpoint

[Migaroez]

Description

This PR introduces a new endpoint that allows partial updates in documents without having to send the full payload. It does this by implementing patching based on jsonpatch/jsonpointer with additional array filtering to query deep into block structures.

Obsoletions

Some existing classes have been marked obsolete as they are a leftovers from a very old attempt at patch endpoints.

Example operations

Replace

{ "op": "replace", "path": "/values[alias=title,culture=null,segment=null]/value", "value": "New Title" }

Add

• To an array with /-: appends to the end
• To an array with an index (e.g., /1): inserts at that position, shifting existing elements
• To an object property: sets the property (creates it if missing)

{ "op": "add", "path": "/values[alias=blocks,culture=null,segment=null]/value/contentData/-", "value": { ... } }

Remove

{ "op": "remove", "path": "/values[alias=blocks,culture=null,segment=null]/value/contentData[key=some-guid]" }

Examples

Update a value inside a blocklist

{
  "operations": [
    {
      "op": "replace",
      "path": "/values[alias=contentBlocks,culture=null,segment=null]/value/contentData[key=ba452058-c92b-46c5-be51-5a0aeedc4e06]/values[alias=headline,culture=null,segment=null]/value",
      "value": "Updated Headline"
    }
  ]
}

Add a block to a Block List

Adding a block requires 3 operations — add the content data, the layout entry, and the expose entry:

{
  "operations": [
    {
      "op": "add",
      "path": "/values[alias=contentBlocks,culture=null,segment=null]/value/contentData/-",
      "value": {
        "contentTypeKey": "151b61c6-79ec-4fd5-88d2-468778193fd7",
        "key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "values": [
          {
            "alias": "headline",
            "culture": null,
            "segment": null,
            "value": "New Block Headline"
          }
        ]
      }
    },
    {
      "op": "add",
      "path": "/values[alias=contentBlocks,culture=null,segment=null]/value/layout/Umbraco.BlockList/-",
      "value": {
        "contentKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "settingsKey": null
      }
    },
    {
      "op": "add",
      "path": "/values[alias=contentBlocks,culture=null,segment=null]/value/expose/-",
      "value": {
        "contentKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "culture": null,
        "segment": null
      }
    }
  ]
}

Documentation

umbraco/UmbracoDocs#7920

[AndyButland]

Looks good @Migaroez - I've left my comments on the code so you can review whilst I'm looking at testing it.

One further point is that there should be an OpenApi.json update with this PR, to include the new models and endpoints.

[AndyButland]

Here's some results from testing (failures could be user error, but I've shared the test data, so please let me know if so).

replace on simple properties (strings, integers, repeated text strings) looks to work fine.

I get a 400 request for remove:

{
  "operations": [
    {
      "op": "remove",
      "path": "/values[alias=blocks,culture=null,segment=null]/value/contentData[key=9e8a7681-5b7d-49fd-8202-2b59865a7089]"
    }
  ]
}

Here's my data:

"values": [
{
	"editorAlias": "Umbraco.BlockList",
	"culture": null,
	"segment": null,
	"alias": "blocks",
	"value": {
		"layout": {
			"Umbraco.BlockList": [
				{
					"$type": "BlockListLayoutItem",
					"contentUdi": null,
					"settingsUdi": null,
					"contentKey": "9e8a7681-5b7d-49fd-8202-2b59865a7089",
					"settingsKey": null
				}
			]
		},
		"contentData": [
			{
				"contentTypeKey": "09598267-c79c-4abb-baf1-ae1552061d63",
				"key": "9e8a7681-5b7d-49fd-8202-2b59865a7089",
				"values": [
					{
						"editorAlias": "Umbraco.TextBox",
						"culture": null,
						"segment": null,
						"alias": "email",
						"value": "test@test.com"
					}
				]
			}
		],
		"settingsData": [],
		"expose": [
			{
				"contentKey": "9e8a7681-5b7d-49fd-8202-2b59865a7089",
				"culture": null,
				"segment": null
			}
		]
	}
}

Also get 400 response for add:

{
  "operations": [
    {
      "op": "add",
      "path": "/values[alias=blocks,culture=null,segment=null]/value/contentData/-",
      "value": {
        "contentTypeKey": "09598267-c79c-4abb-baf1-ae1552061d63",
        "key": "00492d04-d5ff-4e68-883d-42da5d3d79ee",
        "values": [
          {
            "alias": "email",
            "culture": null,
            "segment": null,
            "value": "test2@test.com"
          }
        ]
      }
    },
    {
      "op": "add",
      "path": "/values[alias=blocks,culture=null,segment=null]/value/layout/Umbraco.BlockList/-",
      "value": {
        "contentKey": "00492d04-d5ff-4e68-883d-42da5d3d79ee",
        "settingsKey": null
      }
    },
    {
      "op": "add",
      "path": "/values[alias=blocks,culture=null,segment=null]/value/expose/-",
      "value": {
        "contentKey": "00492d04-d5ff-4e68-883d-42da5d3d79ee",
        "culture": null,
        "segment": null
      }
    }
  ]
}