Replace

Replace swaps what is there for what you send, and anything you leave out is gone. PUT /entities/{id} replaces an entity and PUT /entities/{id}/attrs/{attrId} one attribute. Both answer 204.

Replacing an entity

Replace Entity, PUT /entities/{id}, makes the body the entity. You might send only the attribute you changed, expecting the rest to stay. They don't. Every attribute the body doesn't name is gone afterwards.

http

PUT /ngsi-ld/v1/entities/urn:ngsi-ld:Building:1
Content-Type: application/json

{
    "id": "urn:ngsi-ld:Building:1",
    "type": "Building",
    "name": {
        "type": "Property",
        "value": "Pisa Tower"
    },
    "locatedAt": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:City:Pisa"
    }
}

curl

curl -i -X PUT http://localhost:1056/ngsi-ld/v1/entities/urn:ngsi-ld:Building:1 \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "urn:ngsi-ld:Building:1",
    "type": "Building",
    "name": {
        "type": "Property",
        "value": "Pisa Tower"
    },
    "locatedAt": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:City:Pisa"
    }
}'

rust

let entity = Entity::builder()
    .id(iri!("urn:ngsi-ld:Building:1"))
    .entity_type("Building")
    .property("name", "Pisa Tower")
    .relationship("locatedAt", iri!("urn:ngsi-ld:City:Pisa"))
    .build()?;

let outcome = client.entities().replace(&entity).send().await?;

python

response = requests.put(
    BUILDING,
    json={
        "id": "urn:ngsi-ld:Building:1",
        "type": "Building",
        "name": {
            "type": "Property",
            "value": "Pisa Tower",
        },
        "locatedAt": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:City:Pisa",
        },
    },
)
assert response.status_code == 204

HTTP/1.1 204 No Content

Whatever subCategory the building held is gone. The entity keeps its identity and its createdAt; only the content is new. A replacement omitting expiresAt outlives the expiry the entity had, and a body naming another entity than the path is refused.

If you only mean to change some attributes, use merge. To replace many entities at once, use upsert in a batch.

Replacing one attribute

Replace Attribute, PUT /entities/{id}/attrs/{attrId}, replaces one attribute, addressed by its own path, and swaps the whole instance, its type included. Replacing an attribute without one of its sub-attributes removes that sub-attribute together with everything nested under it:

http

PUT /ngsi-ld/v1/entities/urn:ngsi-ld:Building:1/attrs/temperature
Content-Type: application/json

{
    "type": "Property",
    "value": 22
}

curl

curl -i -X PUT http://localhost:1056/ngsi-ld/v1/entities/urn:ngsi-ld:Building:1/attrs/temperature \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "Property",
    "value": 22
}'

rust

let temperature: AttributeName = "temperature".parse()?;
let attribute = Attribute::from(Property::builder(22).build()?);

let outcome = client
    .entities()
    .replace_attribute(&building, &temperature, &attribute)
    .send()
    .await?;

python

response = requests.put(
    f"{BUILDING}/attrs/temperature",
    json={
        "type": "Property",
        "value": 22,
    },
)
assert response.status_code == 204

HTTP/1.1 204 No Content

The building's temperature now reads 22, its accuracy and the method under it are gone, and humidity beside it is untouched. This is the verb to use when the new reading is the whole truth and a stale sub-attribute should not survive it.

What gets refused

• 400 BadRequestData for a replace whose body names another entity than the path, or holds only the id.
• 404 ResourceNotFound for a replace of an attribute the entity does not have.
• Everything in the common list.