Show/Hide Toolbars

TMS XData Documentation

Navigation: Data Modification

Update an Entity

Scroll Prev Top Next More

To update an entity, clients must perform a PATCH or PUT request to a single entity URL address, providing the JSON representation of the entity in message payload of the request. The entity representation can be full (all possible properties) or partial (a subset of all available properties for the entity type).

 

PATCH method should be preferred for updating an entity as it provides more resiliency between clients and services by directly modifying only those values specified by the client. The semantics of PATCH, as defined in [RFC5789], are to merge the content in the request payload with the entity’s current state, applying the update only to those components specified in the request body. Thus, properties provided in the payload will replace the value of the corresponding property in the entity or complex type. Missing properties of the containing entity will not be altered. In the following example, only properties Name and DogBreed of resource Dog(1) will be updated in the server.

 

PATCH /tms/xdata/Dog(1) HTTP/1.1
Host: server:2001
 
{
  "@xdata.type": "XData.Default.Dog", 
  "Id": 1, 
  "Name": "Willy", 
  "DogBreed": "Yorkshire" 
}

 

PUT method can also be used, but you should be aware of the potential for data-loss for missing properties in the message payload. When using PUT, all property values will be modified with those specified in the request body. Missing properties will be set to their default values. In the following example, properties Name and DogBreed will be updated, and any other existing property of Dog will be set to its default value (strings will be blank, associations will be nil, etc.). If one of missing properties is required and not present, the server might raise an error indicating a required property should have a value.

 

PUT /tms/xdata/Dog(1) HTTP/1.1
Host: server:2001
 
{
  "@xdata.type": "XData.Default.Dog", 
  "Id": 1, 
  "Name": "Willy", 
  "DogBreed": "Yorkshire" 
}

 

Key and other non-updatable properties can be omitted from the request. If the request contains a value for one of these properties the server will ignore that value when applying the update. That's the reason why Id property is not updated in the above examples

 

The entity must not contain associated entities as inline content. If values for navigation properties should be specified, then they must be represented as an association reference. For single-valued (single entity) navigation properties, this will update the relationship (set the value of property to reference the associated object represented in the association reference). The following example updates the Country association of a City object to the country with id equals to 2.

 

PATCH /tms/xdata/City(1) HTTP/1.1
Host: server:2001
 

  "$id": 1,   
  "@xdata.type": "XData.Default.City",   
  "Country@xdata.ref": "Country(2)" 
}

 

Proxy values can be present in the entity payload (for example, when you are sending back a JSON representation previously retrieved from the server, it's possible that proxy values are present), but they are ignored by the server and navigation properties with proxy values are not modified.

 

For update operations (PUT and PATCH), the "xdata.type" annotation is not required. Since you are updating an existing server resource, the type of resource is already known. Actually, including "xdata.type" annotation will force the server to perform a type check, if the type declared in the request doesn't match the type of server resource, an error occurs. So if you include xdata.type annotation in payload, be sure it matches the type of server resource you are trying to update.

 

On successful update, the server returns with a success response and the JSON representation of the updated entity in the message payload. Note that the returned entity might be different from the one sent by the client, since some properties might have been updated automatically by XData Server and/or the database server.