☰
Navigation :

REST-C Messages

Introduction

Any application may use REST-C-… messages to the RestClientApp to request that an outbound REST/HTTP(S) request be made to an external REST/HTTP(S) Server.

The following applications from the core n2svcd module make requests to RestClientApp.

The following LuaApp agents from the core n2svcd module use RestClientApp.

The internal REST-C-… messages are:

Note that this page uses the term “on-the-wire” to refer to the sending or receiving of REST content by the RestClientApp. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).

REST-C-REQUEST

The REST-C-REQUEST message is sent to RestClientApp by any application that wishes to perform an outbound REST request.

Refer to the RestClientApp Configuration documentation for more information on setting default parameters.

The attributes of the REST-C-REQUEST message are:

Field Type Description
rest Object Container for the parameters of the REST request that we are to send.
.host String The hostname to which the REST HTTP(S) request should be sent.
(Default = Host as configured in the RestClientApp)
.port Integer The port number to which the REST HTTP(S) request should be sent.
(Default = Port number as configured in the RestClientApp, or 80 or 443)
.path String The URI path with which the request should be sent.
(Default = Path as configured in the RestClientApp)
.query String The URI query string (the part following "?" in the URI).
(Default = None)
.fragment String The URI fragment string (the part following "#" in the URI).
(Default = None)
.method String The HTTP Request method.
(Default = POST if content is defined, otherwise GET)
.content_type String The HTTP Request Content-Type header value.
(Default = Content-Type as configured in the RestClientApp)
.content String The HTTP Request content.
(Default = None)
.username String Username for authentication (if security is enabled).
(Default = Username as configured in the RestClientApp)
.password String Password for authentication (if security is enabled).
(Default = Password as configured in the RestClientApp)
.security basic/none Security mechanism to use in the REST HTTP(S) request.
(Default = Security as configured in the RestClientApp)
.additional_headers Array of Objects Additional header objects to apply to an outbound request.
(Default = None)
.name String The name of the header attribute to apply.
(Default = None)
.value String The value of the header attribute to apply.
(Default = None)

Note that it is not possible to set or override SSL parameters in the REST-C-REQUEST message. SSL parameters can only be set in the RestClientApp configuration.

REST-C-SENT

The REST-C-SENT message is sent by RestClientApp to the requesting application when the original REST-C-REQUEST is placed on-the-wire.

The attributes of the REST-C-SENT message are:

Field Type Description
rest Object The REST parameters used to encode the final on-the-wire HTTP Request.
This Object has the same structure as the rest Object in REST-C-REQUEST.
Note however that this object will also contain any field values which were filled-in using default values configured within RestClientApp itself.
http String The full HTTP Request message. This field may or may not be present.
The RestClientApp may decide not to supply it in order to reduce traffic on the message bus.

Note that the on-the-wire HTTP Request is not returned in the REST-C-SENT. This is a decision made for efficiency, since these messages can be quite large.

REST-C-RESPONSE

The REST-C-RESPONSE message is sent by RestClientApp to the requesting application when a HTTP Response is received to the original REST-C-REQUEST, or if a failure occurs which indicates that no HTTP Response will be received.

The attributes of the REST-C-RESPONSE message are:

Field Type Description
success 0/1 [Required] Indicates if the request was successful or not.
error String Indicates the reason why the request failed.
Present and applicable only if success == 0.
rest Object Container for the REST response parameters received.
Present only if success == 1.
.code Integer The HTTP Response Status Code (e.g. 200)
.content String The HTTP Request content, if present.
.content_type String The HTTP Request Content-Type header value, if present.
http String The full HTTP Response message. This field may or may not be present.
The RestClientApp may decide not to supply it in order to reduce traffic on the message bus.