qie.callRESTWebService¶
Signature: qie.callRESTWebService(connection, url, operation, content, contentType, parameters, timeout, fullResponse*, connectTimeout*, returnBytes*, tls*, streamToFile*)
Returns: Object wsResponse - the typed result received from the web service call
Call a REST web service.
Note
The contentType parameter is ignored if there is no content being sent. To force the contentType without content add a parameter to your parameters of 'http.header.content-type'.
Note
If fullResponse is 'true', HTTP error codes will be inside the returned http response, instead of throwing an exception.
Note
connectTimeout is optional. When not specified, the connect timeout is taken from timeout when that is set and less than 60000 milliseconds, and is 60000 milliseconds otherwise.
Parameters¶
| Type | Name | Description | Default |
|---|---|---|---|
| String | connection | the name of the web service connection | |
| String | url | the URL endpoint associated with the web service call | |
| String | operation | the type of operation performed | |
| String, File, InputStream, or byte[] | content | the content to include in the web service call (Content encoded call) | |
| String | contentType | the content type (application/xml, application/json, etc.) | |
| Map<String, String> | parameters | a list of parameters to be used by the web service (URL encoded call) | |
| Integer | timeout | the HTTP socket read timeout (in milliseconds), default 60 seconds | |
| Boolean | fullResponse* | (optional) returns the full http response with headers instead of just the response content | false |
| Integer | connectTimeout* | (optional) the HTTP socket connect timeout (in milliseconds) | 60000 |
| Boolean | returnBytes* | (optional) returns a byte array of the response body. Use this for handling binary data. Cannot be used when fullResponse is set to true. |
false |
| String | tls* | (optional) the TLS version to override value from HTTPS connections. Options: []. | |
| String, File, or NetFile | streamToFile* | (optional) output directly to a file to conserve memory. This can be either a string representing the file's full path and file name (i.e. 'c:\\temp\\file.txt'), a java.io.File object or a com.qvera.qie.utils.NetFile object. When used with fullResponse, content element is set to the streamToFile path and file name. Cannot be used with returnBytes. |
Example¶
// Examples of how to use callRESTWebService
// Example GET request (no content)
var parameters = qie.newParameterMap();
var getResult = qie.callRESTWebService(
"Vendor API", // connection - the name of the web service connection
qie.getWsEndpointUrl("Vendor API") + "objects/4", // url - endpoint to call
"GET", // operation - HTTP method
"", // content - none for GET
"application/json", // contentType - ignored when content is empty
parameters // parameters - query parameters
); // <response body>
// Example POST request (content as String - JSON)
var jsonData = `
{
"name": "Rare Pokemon Card",
"data": { "price": 728.99, "color": "Orange" }
}
`;
var postResult = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "objects", // url
"POST", // operation
jsonData, // content (String)
"application/json", // contentType
qie.newParameterMap() // parameters
);
// Example POST request (content as byte[])
var byteContent = [
123,34,116,101,115,116,34,58,34,98,121,116,101,115,34,125
]; // {"test":"bytes"}
var postBytesResult = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "objects", // url
"POST", // operation
byteContent, // content (byte[])
"application/json", // contentType
qie.newParameterMap() // parameters
);
// Example POST request (content as File)
qie.writeFile("/tmp/request.json", jsonData, true);
var fileContent = qie.newFile("/tmp/request.json");
var postFileResult = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "objects", // url
"POST", // operation
fileContent, // content (File)
"application/json", // contentType
qie.newParameterMap() // parameters
);
// Example POST request (content as InputStream)
var inputStreamContent = new java.io.ByteArrayInputStream(
new java.lang.String(jsonData).getBytes("utf-8")
);
var postStreamResult = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "objects", // url
"POST", // operation
inputStreamContent, // content (InputStream)
"application/json", // contentType
qie.newParameterMap() // parameters
);
// Example GET request returning full HTTP response (headers + status + body)
var paramsWithQuery = qie.newParameterMap();
paramsWithQuery.put("param1", "value1");
paramsWithQuery.put("param2", "value2");
var fullHttpResponse = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "objects/4", // url
"GET", // operation
"", // content
"application/json", // contentType
paramsWithQuery, // parameters
60000, // timeout (ms)
true, // fullResponse
30000, // connectTimeout (ms)
false, // returnBytes
"TLSv1.2", // tls
null // streamToFile
); // { status, headers, content }
// Example: returnBytes = true (binary response)
var binaryResponse = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "download/file", // url
"GET", // operation
"", // content
"application/octet-stream", // contentType
qie.newParameterMap(), // parameters
60000, // timeout
false, // fullResponse
60000, // connectTimeout
true // returnBytes
); // byte[]
// Example: streamToFile (write response directly to file)
var streamedFileResult = qie.callRESTWebService(
"Vendor API", // connection
qie.getWsEndpointUrl("Vendor API") + "download/file", // url
"GET", // operation
"", // content
"application/octet-stream", // contentType
qie.newParameterMap(), // parameters
60000, // timeout
false, // fullResponse
60000, // connectTimeout
false, // returnBytes
null, // tls
"/tmp/downloadedFile.bin" // streamToFile
);