Show/Hide Toolbars

TMS XData Documentation

Navigation: Data Modification

Create an Entity

Scroll Prev Top Next More

To create an entity in a collection, clients must perform a POST request to that collection's URL, which can be either the entity set URL address or a navigation property URL address that represents a collection. The POST body must contain a single valid JSON representation of the entity. The entity representation can be full (all possible properties) or partial (a subset of all available properties for the entity type).


Properties in entity representation must be valid properties or navigation properties of the entity type as specified in the entity model. Additional property values beyond those specified in the entity type should not be sent in the request body. The request will fail if unable to persist all property values specified in the request. Missing properties will be set to their default value. If a missing property is required and does not have a default value in the database server, the request will fail.


The following example creates a new Country entity in the server.


POST /tms/xdata/Country HTTP/1.1
Host: server:2001
  "@xdata.type": "XData.Default.Country", 
  "Name": "Brazil"


When creating an entity, the "xdata.type" annotation is not required. If present, it indicates the type of the entity which should be created by the server. It can be useful when creating derived entities, for example, even though you POST to an URL representing an entity set of base types (for example, Animal), the entity being created might be a type inherited from the base type. In the following example the request will create a Cat entity in entity set Animal. It's a valid request. If the provided xdata.type annotation indicates a type that is different or not inherited from the type of entity set being POST'ed, the request will fail.


POST /tms/xdata/Animal HTTP/1.1
Host: server:2001
  "@xdata.type": "XData.Default.Cat", 
  "Name": "Wilbur", 
  "CatBreed": "Persian" 


If "xdata.type" is not present, the created entity will have the same type as the base entity type of the collection addressed by the URL. For example, if client POST to the url "Cat" without "xdata.type" annotation present in payload, an entity of type Cat wil be created.


The entity representation in request payload 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) after entity is created. The following example creates a new City entity which is associated with a Country object of id 2.


POST /tms/xdata/City HTTP/1.1
Host: server:2001

  "$id": 1,   
  "Name": "Frankfurt",   
  "Country@xdata.ref": "Country(2)" 


Proxy values can be present in the entity payload (for example, when you are sending back a modified 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 that were not modified.


When perform POST request to a navigation property URL that represents a collection property, for example, Order(1)/Items which represent items of a specific order, the newly created entity will be automatically associated with  (added to) that collection.


On successful update, the server returns with a 201 Created success response and the JSON representation of the updated entity in the message payload. The response will also contain a Location header that contains the URL of the created entity. 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.