2.2.7.1.3 InsertMediaResource Request

The purpose of the InsertMediaResource request is to enable a BLOB (in other words, a media resource) along with an associated EntityType instance which, potentially with new related entities, is to be inserted into an EntitySet. The base rules and semantics of this request type are defined by AtomPub, as specified in [RFC5023] section 9.6 - Media Resources and Media Link Entries, 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. If an EntityType instance is created via an InsertMediaResource request, the created entity represents an AtomPub Media Link Entry (MLE) and the associated BLOB represents the media resource described by the MLE.

The remainder of this section adds constraints to those defined in AtomPub for this request type.

As specified in [RFC5023] section 9.6, insert requests of this type use the HTTP POST method and the request URI has to represent an AtomPub collection. Because a collection maps to an EntitySet (that is, a collection of entities) in an EDM, the HTTP request line URI MUST be any URI that identifies a collection of entities. If the EntityType associated with the implicitly created MLE defines a concurrency token, a successful response MUST contain an ETag header with a value equal to the value of the concurrency token of the MLE created.

The syntax of an InsertMediaResource request is defined as follows.

 insertMR-Req             = insertEntity-ReqLine     ; section 2.2.7.1.1
                            insertMR-ReqHeaders      
                            CRLF
                            insertMR-ReqBody
  
 insertMR-ReqHeaders  =  [DataServiceVersion]    ; see section 2.2.5.3
                         [MaxDataServiceVersion] ; see section 2.2.5.7
                         [Accept]                ; see section 2.2.5.1
                         [Content-Type]          ; see section 2.2.5.2
                         [Prefer]                ; see section 2.2.5.9
                         [<Slug header as defined in [RFC5023] section 9.7>]
                         *(HTTP-Header-Types)
  
  
 entitySetUri             = <Any data service URI which identifies a collection of entities>
  
 insertEntity-QueryOps    = ; section 2.2.7.1.1
  
 insertMR-ReqBody         = <Any valid HTTP request body> ; see [RFC5023] section 9.6

The syntax of a response to a successful InsertMediaResource request is defined as follows.

 insertMR-Resp             = Status-Line          ; see [RFC2616] section 6.1.1
                            insertEntity-RespHeaders
                            CRLF
                            insertEntity-RespBody
  
 insertMR-RespHeaders      = DataServiceVersion   ; see section 2.2.5.3
                            [ETag]                ; see section 2.2.5.4
                            <Location header, as described in [RFC5023] section 9.6>
                            "Content-Type: "
                            <One of the Media types which defines a representation of
                             an Entity Type>      ; see section 2.2.6
                            [Preference-Applied]  ; see section 2.2.5.10
                            [DataServiceId]      ; see section 2.2.5.11
                            *(HTTP-Header-Types)
  
 insertEntity-RespBody     = <Media Entity in JSON as per [ODataJSON4.0] section 10>
                            / <Entity Type representing a Media Link Entry 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 entityTypeInVJson representation MUST include all name 
                              ; value/pairs denoted in the mleMetadata rule

The syntax of an error response is shown in Error Response (section 2.2.8.1).