Wiki source code of Call a REST Webservice

Last modified by Eva Torken on 2023/09/20 13:50
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In the previous microlearning, we discussed how you can host a REST web service. In this microlearning, we will focus on the other end of the spectrum, namely how to call a REST Webservice. Knowing this will lay the foundation for other microlearnings that will follow this microlearning on various types of authentication that are typically associated with calling a REST Webservice.
3
4 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
5
6 == 1. Prerequisites ==
7
8 * Intermediate knowledge of the eMagiz platform
9
10 == 2. Key concepts ==
11
12 This microlearning centers around calling a REST Webservice within eMagiz.
13 With REST, we mean: A web service that adheres to the RESTful principles
14
15 * To call a REST Webservice you need either:
16 ** A HTTP Outbound Gateway (in case you want a response)
17 ** A HTTP Outbound Channel Adapter (in case you **do not** want a response)
18 * Critical information when configuring this component:
19 ** URL
20 ** HTTP Method (i.e. GET, POST, PUT, etc.)
21 ** Expected Response Type
22 ** Retry Advice
23 ** Authentication
24
25 == 3. Call a REST Webservice ==
26
27 In the previous microlearning, we discussed how you can host a REST web service. In this microlearning, we will focus on the other end of the spectrum, namely how to call a REST Webservice. Knowing this will lay the foundation for other microlearnings that will follow this microlearning on various types of authentication that are typically associated with calling a REST Webservice.
28
29 Calling a REST Webservice within eMagiz can be done with the help of either an HTTP Outbound Gateway or an HTTP Outbound Channel Adapter. In case you want to do something with the response you should opt for the HTTP Outbound Gateway. In scenarios where the response is irrelevant, you should use the HTTP Outbound Channel Adapter. To correctly configure this component you need to consider the following elements:
30
31 * URL
32 * HTTP Method (i.e. GET, POST, PUT, etc.)
33 * Expected Response Type
34 * Retry Advice
35 * Authentication
36
37 We will discuss the first four items in this list in this microlearning. In the microlearnings that will follow this microlearning, we will delve deeper into various authentication possibilities.
38
39 Before we delve into the configuration of the component let us first move to Create and open an exit flow in which we want to call the REST Webservice. When you open the exit flow it will look similar to this:
40
41 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--exit-flow-starting-point.png]]
42
43 Now that we have opened the flow and are in "Start Editing" mode we need to add one of our components (HTTP Outbound Gateway or HTTP Outbound Channel Adapter) to start with. In this microlearning, we are not interested in the response so we will add an HTTP Outbound Channel Adapter to the flow.
44
45 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component.png]]
46
47 === 3.1 URL ===
48
49 Now that we have added the correct component to the canvas it has become time to configure the component correctly. The first thing to configure when calling a REST Webservice is determining and registering the endpoint (URL) eMagiz should call to deliver the message too. As always in scenarios where an information element can change between environments, you should use a property reference and determine the correct value on a per-environment basis.
50
51 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-url.png]]
52
53 === 3.2 HTTP Method ===
54
55 The second part of the configuration is to determine the correct HTTP Method that is linked to the endpoint and does what you want to do. For example, you choose a GET when you want to retrieve certain information from the external party. On the other hand, you would most typically use a POST when you want to deliver new data to the external party. In this example, we want to deliver new information to the external party and therefore will opt for the POST as HTTP Method
56
57 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-http-method.png]]
58
59 === 3.3 Expected Response Type ===
60
61 As you can imagine, for the scenarios in which you do not want a response this field is not as interesting to you. However, if you do want a response you need to be aware that when you leave this empty eMagiz will return the HTTPResponseEntity.
62
63 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-expected-response-type-help-text.png]]
64
65 As you can read in the help text when you do want a response and you want to do something with the body of that response message you should change your expected response type to java.lang.String. That is the reason it has become a best practice when implementing this component to enter by default java.lang.String.
66
67 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-expected-response-type.png]]
68
69 === 3.4 Retry Advice ===
70
71 The fourth and last configuration setting we will discuss in this microlearning is an advanced setting on the HTTP Outbound components. With retry advice, you can guard your solution against temporary connection losses between eMagiz and the external party. As this can happen from time to time the best practice is to configure such a Retry Advice on every HTTP Outbound component. To add the Retry Advice move to the Advanced tab and move down to the Request handler advice chain segment. Within this segment, you will see a button called Retry Advice.
72
73 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-retry-advice-button.png]]
74
75 When you click on the Retry Advice button you will be prompted with a pop-up. In here you need to configure the exact settings
76
77 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-retry-advice-pop-up-empty.png]]
78
79 The best practice for this configuration is as follows:
80
81 * Select the option called Simple Retry Policy
82 * Set the max attempts at 6
83 * Select the Fixed back off policy
84 * Set the backoff period at 5000 (ms)
85
86 When you have done so the configuration should look as follows. The only thing left is to press Save to save your Retry Advice configuration
87
88 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--http-outbound-component-retry-advice-pop-up-filled-in.png]]
89
90 Now that we have configured the HTTP Outbound component to our liking we can press Save on the component level to store our changes. As a result the flow will look as follows:
91
92 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-call-a-rest-webservice--flow-result.png]]
93
94 == 4. Key takeaways ==
95
96 * eMagiz pushes data to or retrieves data from the external party
97 * eMagiz offers two HTTP Outbound components to call a REST Webservice. Choose based on whether you want a response or not
98 * There are five key configuration elements:
99 ** URL
100 ** HTTP Method (i.e. GET, POST, PUT, etc.)
101 ** Expected Response Type
102 ** Retry Advice
103 ** Authentication
104
105 == 5. Suggested Additional Readings ==
106
107 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
108
109 )))((({{toc/}}))){{/container}}{{/container}}