softwaregroup-bgUT Port HTTP Client
Create http/s requests based on
request module
Configuration
id: unique identification of portlogLevel: trace, debug or info.url: remote server URLhttp://example.com:80.uri: remote server request URI/about.html.method: http request methodPOSTorGET.receive: incoming message convert function , return object or promise.send: outgoing message convert function, return object or promise .tls: can be used to enable TLS. For detailed information seetls.createSecureContextand request TLS/SSL ProtocolAccepts the options:
cert- Path to client certificate filekey- Path to client certificate private key filepassphrase- Client certificate passphraseca- Path to trusted root certificate, usually needed for using self signed certificates.
Additional configuration options:
raw: this property can be set in config file only, everything in this property will be merged with current configurationparseResponse: to parse the response or not, defaults totrueparseOptions: to pass certain options when parsing the response (based on the content type) example:
{
"parseResponse": true,
"parseOptions": {
"application/xml": {
"explicitArray": true
}
}
}requestTimeout: in ms, time before timeout error emit, defaults to 30 sec.headers: object containing request header values.namespace: Array containing different namespaces of this port.start: function that will be called once on creation of port. It can be used for setting global variables and initializing objects.
Response
Response is always an object containing response from remote server or error.
If server returns status code different from 200 (OK) or some error occurred
during the process, the response message object will look like:
{
$$:{
mtid: 'error',
errorCode: '',
errorMessage: ''
}
}Message properties:
payload: Contains response data returned from the remote server. If headercontent-typecontains/xmlandparseResponse = truethe data will be converted to javascript object, the same is for Json, if for some reasonparseResponse=trueand there is not parser available for parsing the response, error will be emittedheaders: Response headers.httpStatus: Response status code.
Example
Example index.js configuration file used for making web service requests to
external system. Send and receive are used for modifying message object just
before it is sent and just after response is received.
var xmpParser = require('./xmlParser');
var loadTemplate;
module.exports = {
id: 't24',
type: 'http',
logLevel: 'trace',
url: 'http://twsdevcloudservice.cloudapp.net',
uri: '/swg/swg.svc',
method: 'post',
namespace: ['cbs'],
start: function() {
loadTemplate = this.bus.importMethod('template.load');
},
receive:function(msg) {
if(msg.$$.mtid == 'error'){
return msg;
}
return xmpParser.parse(msg.$$.opcode, msg.payload)
.then(function(res) {
if(res.successIndicator != 'Success'){
msg.$$.mtid = 'error';
msg.$$.errorCode = res.messageId;
msg.$$.errorMessage = Array.isArray(res.message)
? res.message.join('; ')
: res.message;
return msg;
}
msg.payload = res;
return msg;
});
},
send:function(msg) {
msg.headers = {'Content-Type': 'text/xml'};
var templatePath = require.resolve('./' + msg.$$.opcode + '.xml.marko');
var template = loadTemplate(templatePath);
return template.render(msg).then(function(res) {
msg.payload = res;
msg.$$.opcode = msg.opcode || msg.$$.opcode;
return msg;
});
}
};
Open API
ut-port-http provides the possibility to
be used as a swagger client in a semi-automatic
fashion. For this aim an additional configuration
property called openApi must be provided.
Example:
module.exports = (...params) => {
return class swaggerClient extends require('ut-port-http')(...params) {
get defaults() {
return {
namespace: [
'provider1',
'provider2',
'provider3'
],
openApi: {
'provider1': require('./provider2-swagger.json'),
'provider2.segment1': require.resolve('./provider2/segment1-swagger.json'),
'provider2.segment2': require.resolve('./provider2/segment2-swagger.json'),
'provider3': 'http://www.provider3.com/swagger.json'
}
};
}
};
};Note that the openApi configuration property
represents a map where:
the keys determine how the operation IDs of the document will be prefixed. For example if the document is prefixed with key
provider2.segment2and contains a route with operationIdoperationX, then it will be accessible via the methodprovider2.segment2.operationXthrough the bus. Therefore the first parts (before the first dot) of all prefixes must be present in thenamespacearray.the values are the documents themselves. All three approaches are acceptable as a value:
- the content of the swagger document
- path to a local swagger document
- url for obtaining the document with http
GETrequest
The message format for calling these auto-generated swagger methods has the following specifics:
- can have a
bodyproperty which will be used as a payload - can have a
paramsproperty which ill be used for extractingpath,queryandheaderparameters.
Example:
await utMethod('provider2.segment2.operationX')({
body: {
payloadProp1: 'payloadValue1',
payloadProp2: 'payloadValue2'
},
params: {
param1: 'value1',
param2: 'value2'
}
});For more information see ut-openapi request format