EGL REST-RPC message structure

The HTTPRequest message has the following characteristics:

• The header contains key:Content-Type with the following value: application/json. The method is POST.
• In essence, the body of the message contains the following EGL Record definition in JSON format:

  Record EGL_REST_RPC_Request
  
     //name of the function to be invoked
     method string;
  
     //IN and INOUT parameters in the service parameter-list order
     params any[];
  end

When the EGL service function returns successfully, the HTTPResponse message has the following characteristics:

• The status code in the header is set to 200.
• In essence, the body of the message contains one of the following two EGL Record definitions in JSON format:

  // For a response with one value
  Record EGLRESTRPCSingleReturnParamResponse
     result any?;
     error EGLRESTRPCResponseError?;
  end
  
  // For a response with multiple values, as described later
  Record EGLRESTRPCMultipleReturnParamResponse
     result any[];
     error EGLRESTRPCResponseError?;
  end

Response parameters include service parameters that are modified by OUT or INOUT, as well as a value returned from the service function. Here are the variations:

• In the absence of any response parameters, whether OUT, INOUT, or return, the requester receives an empty JSON object.
• If only one response parameter is in use, the requester receives a JSON object of type EGLRESTRPCSingleReturnParamResponse.
• If multiple response parameters are in use, the requester receives a JSON object of type EGLRESTRPCMultipleReturnParamResponse. The result array shown earlier includes the response parameters in the parameter-list order and then the value returned from the service function.

When the EGL service function returns with an error, the HTTPResponse message has the following characteristics:

• The status code in the header is set to 500.
• In essence, the body of the message contains following structure in JSON format:

  Record EGLRESTRPCResponseError
     error JSONRPCError;
  end
  
  Record JSONRPCError
     name string;
     code string;
     message string;
     error EglRpcException
  end;
  
  Record EglRpcException
     name string;
     messageID string;
     message string;
  
     // the next fields are present 
     // if the type is egl.core.ServiceInvocationException 
     source? int; 
     detail1? string;
     detail2? string;
     detail3? string;
  end

The fields in the JSONRPCError record are as follows:

name

The value "JSONRPCError".

code

The exception message ID.

message

The exception message.

error

A set of fields represented in the EglRpcException record. First is the name field, which contains the fully qualified name of an exception record; in most cases, "egl.core.ServiceInvocationException". The other fields are from the EGL exception, as described in “EGL exception records.”

Consider an EGL REST-RPC service that is structured as follows:

Service HelloWorld
   function emptyParams()
      ;
   end
   function singleReturnParam( p1 string in)returns(string)
      ;
   end
   function multipleReturnParams( p1 string? )returns(Wrapper?)
      ;
   end
   function throwsException()
      ;
   end
end

Record Wrapper
   text string;
   length int;
end

No parameters:
   Request body:{"method" : "emptyParams", "params" : []}
   Response body:{}

One return parameter:
   Request body:{"method" : "singleReturnParam", "params" : ["Joe"]}
   Response body:{"result" : "Hello Joe"}

Multiple return parameters:
   Request body:{"method" : "multipleReturnParams", "params" : ["Joe"]}
   Response body:{"result" : ["Hello Joe", {"text" : "Hello Joe", "length" : 9}]}

   Request body:{"method" : "throwsException", "params" : []}
   Response body:
   {"error" : 
      { "name"   : "JSONRPCError", "code" : "EGL1539E", 
        "message" : "EGL1539E An exception occurred...",
        "error"  : 
           {"messageID" : "EGL1539E", "message" : "EGL1539E An exception occurred...", 
            "source" : 4, "detail1" : "500", "detail2" : "FAILED", 
            "detail3" : "java.net.ConnectException:Connection refused", 
            "name" : "egl.core.ServiceInvocationException"
           }
      }
   }