Replacing a Sublist
During sublist replacements, lines of a keyed sublist are updated if the line contains matching keys, other lines are removed, and the remaining unmatched lines from the request are added. For non-keyed sublists, all lines are always removed and replaced by lines that are in the incoming request. The following examples show POST and PATCH operations with a replace query parameter.
Request Body – Replacing a Default Keyed Sublist
POST .../myrecord?replace=sublist
{
"body1": "inserted body text 1",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "inserted line 1" },
{ "key1": "b", "key2": "2", "col": "inserted line 2" }
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" }
]
}
}
Response – Post State
Response:
201 Created
Location: .../myrecord/101
{
"body1": "inserted body text 1",
"body2": "default body text 2",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "inserted line 1" },
{ "key1": "b", "key2": "2", "col": "inserted line 2" },
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "default line 1" },
{ "col": "default line 2" },
{ "col": "default line 0" },
{ "col": "inserted line 1" },
{ "col": "inserted line 2" },
]
}
}
Keyed sublist lines are updated if the key matches, other lines are removed, and unmatched lines from the request are created as new. All lines of non-keyed sublists are added. The operation fails if any replaced default sublist line is read-only.
Request Body – Replacing a Default Non-Keyed Sublist
POST .../myrecord?replace=unkeyedsublist
{
"body1": "inserted body text 1",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "inserted line 1" },
{ "key1": "b", "key2": "2", "col": "inserted line 2" }
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" }
]
}
}
Response – Post State
Response:
201 Created
Location: .../myrecord/101
{
"body1": "inserted body text 1",
"body2": "default body text 2",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "inserted line 1" },
{ "key1": "b", "key2": "2", "col": "inserted line 2" },
{ "key1": "X", "key2": "0", "col": "default line 0" },
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" },
]
}
}
Keyed sublist lines are updated if the key matches, otherwise, a new line is created. All lines of non-keyed sublists are removed and then created as new. The operation fails if any replaced default sublist line is read-only.
Request Body – Replacing a Keyed Sublist
PATCH .../myrecord/100?replace=sublist
{
"body1": "replaced body text 1",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" }
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" }
]
}
}
Response – Post State
Response:
204 No Content
Post State:
{
"body1": "replaced body text 1",
"body2": "previous body text 2",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" },
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "previously present line 1" },
{ "col": "previously present line 2" },
{ "col": "previously present line 0" },
{ "col": "inserted line 1" },
{ "col": "inserted line 2" },
]
}
}
Keyed sublist lines are updated if the key matches, other lines are removed, and unmatched lines from the request are created as new. All lines of non-keyed sublists are added.
Request Body – Replacing a Non-Keyed Sublist
PATCH .../myrecord/100?replace=unkeyedsublist
{
"body1": "replaced body text 1",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" }
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" }
]
}
}
Response – Post State
Response:
204 No Content
Post State:
{
"body1": "replaced body text 1",
"body2": "previous body text 2",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" },
{ "key1": "X", "key2": "0", "col": "previously present line 0" },
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" },
]
}
}
Keyed sublist lines are updated if the key matches, otherwise, a new line is created (in other words, sublist lines are merged). All lines of non-keyed sublists are removed and then created as new.
Request Body – Replacing Multiple Sublists
The following operation is a combination of the previous operations.
PATCH .../myrecord/100?replace=sublist,unkeyedsublist
{
"body1": "replaced body text 1",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" }
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" }
]
}
}
Response – Post State
Response:
204 No Content
Post State:
{
"body1": "replaced body text 1",
"body2": "previous body text 2",
"sublist" : {
"items" : [
{ "key1": "a", "key2": "1", "col": "replaced line 1" },
{ "key1": "b", "key2": "2", "col": "replaced line 2" },
]
},
"unkeyedsublist" : {
"items" : [
{ "col": "inserted line 1" },
{ "col": "inserted line 2" },
]
}
}