2.2.7.5 Invoke Request Types

The purpose of the Invoke request is to enable a client to call a FunctionImport, as specified in [MC-CSDL] section 2.1.15, that is exposed by a service operation in a data service. Note that this excludes function imports that are used to specify either actions (section 2.2.1.3) or functions (section 2.2.1.4). AtomPub [RFC5023] does not define operations of this type. As such, this request type is not based on any AtomPub-defined [RFC5023] request.

Invoke Request MUST use the HTTP method specified by the data service's metadata document, as described in Conceptual Schema Definition Language Document for Data Services (section 2.2.3.7.2), and the URI specified by the client in the HTTP request line MUST be a URI which identifies a service operation, as described in Resource Path: Semantics (section 2.2.3.5).

If the FunctionImport, as specified in [MC-CSDL], that is exposed by a service operation requires input parameters, those parameters MUST be provided, as specified in Service Operation Parameters (section 2.2.3.6.3).

If the Invoke request is not successful (for example, an error occurred while processing the request), the response MUST be formatted according to Error Response (section 2.2.8.1).

The syntax of an Invoke request is defined as follows:

 invoke-Req    =     invoke-ReqLine
                           invoke-ReqHeaders
                           CRLF
  
 invoke-ReqLine      =     <Any standard or custom HTTP method>
                           ; The method supported for a particular 
                           ; service operation
                           ; is defined by the httpMethod CSDL annotation
                           ; defined in section 2.2.3.7.2
                           SP serviceOperationUri invoke-QueryOps
                           SP HTTP-Version
                           CRLF
  
 invoke-ReqHeaders   =     [DataServiceVersion]        ; see section 2.2.5.3
                           [MaxDataServiceVersion]     ; see section 2.2.5.7
                           *(HTTP-Header-Types)
  
 serviceOperationUri =     <Any Resource Path identifying a Service Operation>
                            ; see section 2.2.3 and section 2.2.3.5
  
 invoke-QueryOps      = ["?" (sysQueryOption / customQueryOption / serviceOpParam)
                         *("&" (customQueryOption / serviceOpParam) )]
                         ; see section 2.2.3.1 & section 2.2.3.6.3

The syntax of a response to a successful Invoke request is defined as follows:

 invoke-Resp         =      Status-Line                 ; see [RFC2616] section 6.1.1  
                            invoke-RespHeaders 
                            CRLF
                            invoke-RespBody
  
 invoke-RespHeaders  =      DataServiceVersion          ; see section 2.2.5.3   
                            [ETag]                      ; see section 2.2.5.4   
                            *(HTTP-Header-Types)
  
 invoke-RespBody     =      invoke-RespBody-collEt
                            / invoke-RespBody-et
                            / invoke-RespBody-collCt
                            / invoke-RespBody-ct
                            / invoke-RespBody-collPrim
  
 ; a Function Import which returns a collection of entities
 invoke-RespBody-collEt   = retrieveEntitySet-RespBody ; see section 2.2.7.2.1
        
  
 ; a Function Import which returns an entity
 invoke-RespBody-et       = retrieveEntity-RespBody    ; see section 2.2.7.2.2
  
 ; a Function Import which returns a collection of complex types
 invoke-RespBody-collCt   = <Collection of complex values formatted by using JSON
                             as per [ODataJSON4.0] section 7.4>
                            /<Collection of complex type instances formatted by using XML 
                              as per section 2.2.6.5.2>
                            /(begin-object 
                              quotation-mark "d" quotation-mark 
                              name-seperator 
                              entityCollCTInVJson
                              end-object) 
                              ; see section 2.2.6.3.5   
  
 ; a Function Import which returns a single Complex Type
 invoke-RespBody-ct       = retrieveCT-RespBody        ; see section 2.2.7.2.3
  
 ; a Function Import which returns a collection of primitives
 invoke-RespBody-collPrim = <Collection of primitive values formatted by using JSON
                             as per [ODataJSON4.0] section 7.3>
                            /<Collection of primitive type values formatted by using XML 
                             as per section 2.2.6.5.4>
                            /(begin-object 
                              quotation-mark "d" quotation-mark 
                              name-seperator 
                              entityCollPrimValueInVJson) 
                              end-object
                              ; see section 2.2.6.3.7    
  
 quotation-mark          = ; see [RFC4627] section 2.5
  
 ; a Function Import which returns a single primitive type value
 invoke-RespBody-prim     = retrievePP-RespBody        ; see section 2.2.7.2.4