2.2.7.5.1 Invoke Action Request

Applies to the OData 3.0 protocol

The purpose of the Invoke Action request is to enable a client to call a FunctionImport, as specified in [MC-CSDL] section 2.1.15, that is exposed as an action (section 2.2.1.3) in a data service.

An Invoke Action request MUST use an HTTP POST. Additionally, the URI specified by the client in the HTTP request line MUST be a URI that identifies an action, as described in Resource Path: Semantics (section 2.2.3.5).

If the FunctionImport, as specified in [MC-CSDL], that is exposed as an action requires input parameters other than the binding parameter, those parameters MUST be provided in the body of the request by using the application/json or application/json;odata=verbose Content-Type, as specified in Action Parameters (section 2.2.3.6.5).

If the Invoke Action 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).

In particular, if the Invoke Action request includes an If-Match (section 2.2.5.5) header that contains an ETag for the resource against which the request is bound, servers MUST check that version of the ETag against the latest server known value. If the server discovers the client’s version is out of date, the server MUST fail the request with a 412 Precondition Failed response (section 3.2.8).

The OData protocol provides a way to pass action parameters in JSON and Verbose JSON formats only.

The syntax of an Invoke Action request is defined as follows:

 invoke-Req                = invokeAction-ReqLine
                             invokeAction-ReqHeaders
                             CRLF
                             invokeAction-Parameters
  
 invokeAction-ReqLine      = "POST"
                             SP actionUri
                             SP HTTP-Version
                             CRLF
  
 invokeAction-ReqHeaders   = [DataServiceVersion]        ; see section 2.2.5.3
                             [MaxDataServiceVersion]     ; see section 2.2.5.7
                             [If-Match]                  ; see section 2.2.5.5
                             ["Content-Type" WSP "=" WSP "application/json;odata=verbose" CRLF]
                             *(HTTP-Header-Types)
  
 actionUri                 = <Any Resource Path identifying an Action>
                             ; see section 2.2.3 and section 2.2.3.5
  
 invokeAction-Parameters   = <Action parameters in JSON as per [ODataJSON4.0] section 17>
                             / begin-object
                             [ actionParameterNVP
                             *(value-seperator actionParameterNVP) ]
                             end-object
  
 actionParameterNVP        = quotation-mark actionParameterName quotation-mark
                             name-seperator
                             actionParameterValue
  
 actionParameterName       = *pchar
                             ; the name of a parameter to the Action
                             ; as defined by the corresponding FunctionImport.
  
 actionParameterValue      = "null" | typeInVJson
  
 typeInVJson                = <Any type (or collection) serialized in Verbose JSON>
                             ; formatted as per the rules described in section 2.2.6.3

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

 invokeAction-Resp         = Status-Line        ; see [RFC2616] section 6.1.1  
                             invoke-RespHeaders ; section 2.2.7.5
                             CRLF
                             [invoke-RespBody]  ; missing if the Action has no ReturnType