P137 - Rest client plugin
The REST client plugin is a plugin that provides Architect actions that can be used within processes to perform HTTP requests against Webservices.
Plugin dependencies
This plugin has direct dependency towards the P173 - Serialization plugin. That means, whenever you intend do use the REST client plugin in your application, you should ensure that in the final integrated application, there is P173 - Serialization plugin included.
To avoid confusion and extra avoidable integrations and generations - if you include REST client plugin in a component, always include the Serialization plugin as well.
-
As a rule of thumb - when you include one of the below, also add P173 - Serialization plugin to the same component
- P137 - REST client
- P176 - Restful webservice
- P198 - REST Data webservice
- P195 - Data gathering
- P220 - Novulo OAuth2 plugin
-
There are rules in the composer that are in place so you are warned about the missing plugin or when using incompatible plugin revisions.
HttpAction and RESTxxx actions
The REST Client plugin provides a lot of actions - all of them to perform a HTTP request, the difference is in the used HTTP verb.
Since revision 119564 the HttpAction has been introduced, that is meant to combine all the different RESTxxx actions into a single action, which does not expose any plugin configuration and everything is set in the Parameters tab of the HttpAction .
Revision 119564 deprecates the RESTxxx actions and it is no longer recommended to use them. It is planned that the RESTxxx actions are phased out and will no longer be maintained. Any further related enhancements and bugfixes will be done on the HttpAction. When possible in the Architect, the RESTxxx actions will be removed from the palette and at some point dropped from the plugin completely.
Plugin configuration explanation
This plugin action does not have Plugin Configuration, it needs only Parameters.
Parameters
This is what the HttpAction looks like in the Architect:
| Name | Type | Description | Example value |
|---|---|---|---|
| url | URL | The url against which the HTTP request has to be made. | http://localhost:50295/rest/file_upload |
| method | String | The HTTP method for the request. These are GET/POST/PATCH/PUT/DELETE | POST, GET |
| context_id | String | Used in combination with the Config headers. This is the pre-fix for the value to retrieve from the webconfig. For example I have the following webconfig key: | The webconfig key is : The context_id is Ddrest |
| skip_request_body_serialization | Boolean (default false) | Used to bypass serializers. Set to true to not serialize the “request_body_object” parameter. That means request_body_object should be a string | |
| skip_response_body_serialization | Boolean (default false) | Used to bypass deserializers. Set to true to not deserialize the response object that is received in the response. | |
| remove_underscore_from_ids | Boolean (default false) | When there is “id” tuple key in the object to serialize, the Novulo JSON Serializer makes it “id" due to compatibility reasons. Set it to true to remove the "” | |
| literal_headers | List<Tuple<String,Mixed>> | Literal list with the desired headers for the request. Needs at least “Content-Type” in order to be able to set the content-type of the request (and instantiate Serializer when needed) | Depends on your request, but for example: [ <“Accept”,“/”>, <“Accept-Encoding”,“gzip, br, deflate, zstd”>, <“Content-Type”,“application/json”>] |
| config_headers | List<Tuple<String,Mixed>> | Any headers, the value of which should be set with a value from the webconfig. See also context_id explanation; For webconfig key “REST.Ddrest.Header.Authorization” we would get the value of the tuple replaced with the value property of the webconfig key | [<“Authorization”, “Authorization”>] at runtime is translated to [<“Authorization”, “Bearer xxxxxx” >] |
| files | List<Tuple<String,Mixed>> | Any files that need to be sent with the request. Providing values here automatically makes the request of content-type “multipart/form-data”. Note, that if you have other non-file data, the provided Content-Type header value in the literal headers should indicate what Serializer should be used to handle the request_body_object. The value is of [<string,mixed>] type, where the key of the tuple is the name of the expected file parameter at the receiving party. I.O.W The tuple key will be used as the “name” parameter in the Content-Disposition header of the multipart body. See this | My Webservice endpoint expects a file parameter name “file_value”. So i have to set the following value: [<“file_value”,file:load(754)>], where the file:load is replaced with reference to your file record] |
| timeout_ms | Int | After what time (in milliseconds) the Client should abort the request | Int value. Any reasonable amount required to send a request to the targeted webserver and get response from it. |
| certfile | File | File reference to a certificate to use in order to authenticate the request. | A reference to the Cert file in your application. |
| certpassword | String | Password for the certfile parameter (if the certificate file is password protected) | |
| request_body_object | Mixed | Can be string, can be <string,mixed>, can be list of <string,mixed>. If it is a string, then you should set skip_request_body_serialization to true |
Return values
The plugin action has the following return values:
| Name | Type | Explanation |
|---|---|---|
| success | Boolean | Default Novulo Action return value. True - if the action succeeded, false if error occured |
| error | Messages | Default Novulo Action return value. NULL if success is True, if success is False - the message is set with description on what went wrong. |
| response_object | Mixed | The response body. If parameter skip_response_body_serialization is set to true, then this would be a string. If set to false, then the response body would be serialized to one of: - Tuple<String,Mixed>, - List<Tuple<String,Mixed>>, - List<List<Tuple<String,Mixed>>> |
| response_object_ntype_string** | String | The Novulo datatype of the response_object |
| response_status | Int | The HTTP Response Status code of the HTTP Response (i.e. 200, 400, 401, 404, 500 etc.) |
| response_body | String | The raw response body as String. This is not Serialized |
| request_uri | String | The URL against which the Http request has been made. |
| request_body | String | The raw request body as a String that was sent with the Http request. |
| request_time | Int | The time (in milliseconds) it took to get a response from the server |
| has_timed_out | Boolean | True if a Request timeout occurred (HTTP 408) |
| response_status_message | String | The status message of the returned HttpStatusCode (i.e. 200 = OK, 400 = BadRequest etc.) |
** response_object_ntype_string is missing from the plugin action definition in revision 119564. To be added… You can use the following combination to get to the response_object datatype (until its added in the HttpAction)
- Expression tools - ExpressionToolsToExpressionString, with parameter being the http_action.response_object
- Expression tools - EvaluateExpression, with parameter “expression” being the result of ^
- The result of EvaluateExpression contains the NovuloDataType of the Object, under the return value named resulttype.