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.
TesterApp
(initates outbound REST requests)
The following LuaApp agents from the core n2svcd
module use RestClientApp.
RestLuaAgent
(initates outbound REST requests)
The internal REST-C-… messages are:
REST-C-REQUEST
REST-C-SENT
REST-C-RESPONSE
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. |