The data.world public API supports several options for programmatically making updates to resources on the platform. PATCH
is a method for making partial updates to individual records, such as adding tags, changing a description, or modifying a title.
In the next two weeks, we will be making a change to the way PATCH
endpoints modify list values. We outline these changes below.
Existing Merge Behavior
Lists are merged with existing values on PATCH requests
- A dataset has tags: [
tag A
, tag B
] - A
PATCH
request is sent to /datasets/democorp/my-example-dataset
with body: { "tags": [ "tag C", "tag D" ] }
- The dataset is updated to reflect tags: [
tag A
, tag B
, tag C
,tag D
] - A
PATCH
request is sent to /datasets/democorp/my-example-dataset
with payload: { "tags": [] }
- No change is applied and the tags remain: [
tag A
, tag B
, tag C
,tag D
]
New Replace Behavior
Lists replace existing values on PATCH requests
- A dataset has tags: [
tag A
, tag B
] - A
PATCH
request is sent to /datasets/democorp/my-example-dataset
with body: { "tags": [ "tag C", "tag D" ] }
- The dataset is now updated to have tags: [
tag C
,tag D
]. tag A
and tag B
have been removed. - I send a
PATCH
request to /datasets/democorp/my-example-dataset
with body: { "tags": [] }
- The dataset has been updated to remove all tags.
Why we are making this change
Today, PATCH
can be used to add, modify, or remove fields for all non-list values. With the current merge logic, items can only be appended to list values using PATCH
. As a consequence, if you want to remove or reorder the items in a list, you must use the PUT
method, which does not support partial updates and requires a full overwrite of the existing record. The new logic to overwrite list values will allow users to make partial updates to records that remove or modify the order of items in the list without needing to modify the entire record.
This new logic primarily impacts tags, file labels, collections, and multi-select custom metadata fields.