☰
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)
.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)
.content_type String The HTTP Request Content-Type header value.
(Default = default content type as configured in the RestClientApp)
.content String The HTTP Request content.
(Default = None)
.http_headers Array of Objects Additional user-level header objects to apply to an outbound HTTP Request (see below for object structure).
These headers are added after any headers defined by static RestClientApp application configuration.
You should not set the Content-Type or Content-Length headers.
(Default = No Additional Headers)

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.

Each object in the rest.http_headers Array for REST-C-REQUEST has the following structure.

Field Type Description
.name String [Required] The name of the HTTP Request header.
.value String [Required] The full string value of the HTTP Request header.
.replace 0 / 1 If 1 then all previous headers of this name are removed, and this header replaces them.
(Default = Append to the existing headers, do not replace)

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 returned HTTP Response status code, e.g. `200`.
.content_type String The HTTP Response Content-Type header value, if present.
.http_headers Array of Object The list of HTTP headers parsed from the HTTP Response (see below for object structure).
All HTTP headers are present, including Content-Length and Content-Type.
If a HTTP header was repeated in the HTTP Response, then it is repeated in this Array.

Each object in the rest.http_headers Array for REST-C-RESPONSE has the following structure.

Field Type Description
.name String [Required] The name of the HTTP Response header.
.value String [Required] The full string value of the HTTP Response header.