2.2.7.1.1 InsertEntity Request
The purpose of the InsertEntity request is to enable a new EntityType instance, potentially with new related entities, to be inserted into an EntitySet. The base rules and semantics of this request type are defined by AtomPub, as specified in [RFC5023] section 5.3 – Creating a Resource, and, as described in Abstract Data Model (section 2.2.1), Entity Data Model (EDM) constructs are mapped directly to data model concepts used in AtomPub. For example, EntityTypes are AtomPub Entry Resources and collections of entities (entity sets and so on) are AtomPub collections. This section adds constraints to those defined in AtomPub for this request type.
As specified in [RFC5023] section 9.2, insert requests use the HTTP POST method and the request URI has to represent an AtomPub collection. Because a collection maps to a conceptual schema definition language (CSDL) in an EDM, the HTTP request line URI MUST be any valid data service URI, as defined in URI Format: Resource Addressing Rules (section 2.2.3), which identifies a collection of entities.
[RFC5023] section 9.2 states that the request body in the POST might be an AtomPub Entry Resource (which maps to an EntityType instance in an EDM) represented as an Atom Entry document. This document extends this rule to allow additional representations of an Entry Resource to be posted to a URI representing a collection. This document defines three such representations of EntityTypes that map to Entry Resources: AtomPub as defined in Entity Type (as an Atom Entry Element) (section 2.2.6.2.2), JSON as defined in Entity [ODataJSON4.0] section 6, and Verbose JSON as defined in Entity Type (as a Verbose JSON Object) (section 2.2.6.3.3).
When the request body is a representation of an Entry Resource (Entity Type in EDM terms), the client MAY specify whether the resource/entity is to be automatically linked to other already existing entities in the data service. For example, a new order entity might need to be bound to an existing customer entity in a customer relationship management focused data service. Such linking is to be supported only if the EntityType of the to-be-inserted entity defines a NavigationProperty which associates the new entity and the to-be-related entity.
To bind the new entity to one or more (as defined by the cardinality of the NavigationProperty) existing entities, the client MUST include the required binding information in the representation of the associated NavigationProperty in the request payload.
To bind the new entity to an existing entity by using the Atom format, the NavigationProperty MUST be represented, as specified in Navigation Property (section 2.2.6.2.4), with one exception: the href attribute of the atom:link element has to represent the URI of the entity to be linked to.
To bind the new entity to an existing entity by using the preferred OData 3.0 JSON format, see [ODataJSON4.0] section 8.5.
To bind the new entity to an existing entity by using the Verbose JSON format, the NavigationProperty MUST be represented using the inline representation of a NavigationProperty, as specified in Inline Representation (section 2.2.6.3.9.1), with the inlined entities represented using only the "__metadata" name/value pair (the properties of each inlined entity SHOULD NOT be provided).
In addition to supporting the insertion of a new EntityType instance (E1) into an EntitySet, this request type allows inserting new entities related to E1 (described by a NavigationProperty on the EntityType associated with E1) using a single InsertEntity request. For example, in a customer relationship management focused data service, a new customer entity and new related order entities could be inserted by using a single InsertEntity request. This form of an InsertEntity request is also known as a "deep insert".
To insert a new EntityType instance (E1) and related entities, the related entities MUST be represented using the inline representation of the NavigationProperty (associated with E1) that identifies the link to the (to-be-inserted) related entities, as described in Inline Representation (section 2.2.6.3.9.1) and Inline Representation (section 2.2.6.2.6.1).
The syntax of an InsertEntity request is defined as follows.
-
insertEntity-Req = insertEntity-ReqLine insertEntity-ReqHeaders CRLF insertEntity-ReqBody insertEntity-ReqLine = "POST" SP entitySetUri insertEntity-QueryOps SP HTTP-Version CRLF insertEntity-ReqHeaders = [DataServiceVersion] ; see section 2.2.5.3 [MaxDataServiceVersion] ; see section 2.2.5.7 [Content-Type] ; see section 2.2.5.2 [Prefer] ; see section 2.2.5.9 *(HTTP-Header-Types) entitySetUri = <Any Resource Path which identifies collection of entities> ; see section 2.2.3 and section 2.2.3.5 -- URI1 & URI6 insertEntity-QueryOps = ["?" customQueryOption *("&" customQueryOption)] ; see section 2.2.3.1 insertEntity-ReqBody = <Entity in JSON format as per [ODataJSON4.0] section 6> / <Entity Type in Verbose JSON format as per section 2.2.6.3.3> / <Entity Type in Atom format as per section 2.2.6.2.2> / <Entity Type in Atom Format with Customizable Feeds Property Mapping as per section 2.2.6.2.2.1>
The syntax of a response to a successful InsertEntity request is defined as follows.
-
insertEntity-Resp = Status-Line ; see [RFC2616] section 6.1.1 insertEntity-RespHeaders CRLF insertEntity-RespBody insertEntity-RespHeaders = DataServiceVersion ; see section 2.2.5.3 [ETag] ; see section 2.2.5.4 [Preference-Applied] ; see section 2.2.5.10 [DataServiceId] ; see section 2.2.5.11 <Location header, described in [RFC5023] section 9.2> "Content-Type: " <One of the Media types which defines a representation of an Entity Type> ; see section 2.2.6 *(HTTP-Header-Types) insertEntity-RespBody = <Entity in JSON format as per [ODataJSON4.0] section 6> / <Entity Type in Atom format as per section 2.2.6.2.2> / (begin-object quotation-mark "d" quotation-mark name-seperator entityTypeInVJson end-object) ; see section 2.2.6.3.3
The syntax of an error response is shown in Error Response (section 2.2.8.1).