Append

Append is POST /entities/{id}/attrs. It answers 204, or 207 when some attributes are left unwritten.

Append adds the attributes in the body. By default it overwrites an attribute that is already there, so a value you append replaces the old one without a warning.

http

POST /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567/attrs
Content-Type: application/json

{
    "colour": {
        "type": "Property",
        "value": "red"
    }
}

curl

curl -i http://localhost:1056/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567/attrs \
  -H 'Content-Type: application/json' \
  -d '{
    "colour": {
        "type": "Property",
        "value": "red"
    }
}'

rust

let fragment = EntityFragment::builder()
    .property("colour", "red")
    .build()?;

let outcome = client
    .entities()
    .append_attributes(&id, &fragment)
    .send()
    .await?;

python

response = requests.post(
    f"{ENTITY}/attrs",
    json={
        "colour": {
            "type": "Property",
            "value": "red",
        },
    },
)
assert response.status_code == 204

HTTP/1.1 204 No Content

With ?options=noOverwrite, an attribute the entity already has keeps its value. The new attributes are still written. When some attributes are left unwritten, the answer is 207 with an updated list and a notUpdated list, which gives the reason for each one. In Rust, the call takes .overwrite(Overwrite::Keep), and the outcome is UpdateOutcome::Partial when some attributes were left out.

http

POST /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567/attrs?options=noOverwrite
Content-Type: application/json

{
    "colour": {
        "type": "Property",
        "value": "blue"
    }
}

curl

curl -i 'http://localhost:1056/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567/attrs?options=noOverwrite' \
  -H 'Content-Type: application/json' \
  -d '{
    "colour": {
        "type": "Property",
        "value": "blue"
    }
}'

rust

let fragment = EntityFragment::builder()
    .property("colour", "blue")
    .build()?;

let outcome = client
    .entities()
    .append_attributes(&id, &fragment)
    .overwrite(Overwrite::Keep)
    .send()
    .await?;

python

response = requests.post(
    f"{ENTITY}/attrs",
    params={"options": "noOverwrite"},
    json={
        "colour": {
            "type": "Property",
            "value": "blue",
        },
    },
)
assert response.status_code in (204, 207)

Update writes the same way. It changes the attributes the entity has and adds the ones it doesn't. The difference is noOverwrite, which only an append has, to keep an attribute the entity already holds.

What gets refused

• 404 ResourceNotFound when the entity doesn't exist.
• 207 when some attributes were left unwritten, as with noOverwrite. Each entry in notUpdated carries its reason.
• Everything in the common list.