Skip to Content

Wiki source code of Configuration REST web service

Last modified by Erik Bakker on 2024/02/22 11:56
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 {{error}}
3 Note that the functionality mentioned in this microlearning will become obsolete when migrating to the 3rd generation runtime.
4 {{/error}}
5
6 In this microlearning, we will discuss how you can manually host a REST web service outside the API management layer of eMagiz.
7 The main idea of hosting a web service, whether it be SOAP/XML or REST/JSON (or any other combination) is that the process you are supporting wants to be informed in real-time or wants to execute actions in real-time without any support from the integration. In other words, you want the application to push the requests to eMagiz instead of eMagiz having to pull the data out of an application.
8
9 In this microlearning, we will focus on the REST web service and how you can host this in eMagiz through some simple steps.
10 To summarize, hosting a REST web service gives you:
11
12 * A way to listen for messages instead of actively needing to pull them.
13 * A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)
14
15 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
16
17 == 1. Prerequisites ==
18
19 * Intermediate knowledge of the eMagiz platform
20
21 == 2. Key concepts ==
22
23 This microlearning centers around configuring a REST web service.
24 With configuration, we mean: The steps you need to execute to achieve a certain result
25 With REST, we mean: A web service that adheres to the RESTful principles
26
27 * The application (client) pushes the data to eMagiz
28 * To summarize, hosting a REST web service gives you:
29 ** A way to listen for messages instead of actively needing to pull them.
30 ** A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)
31
32 == 3. Configuration REST web service ==
33
34 In this microlearning, we will discuss how you can manually host a REST web service outside the API management layer of eMagiz.
35 The main idea of hosting a web service, whether it be SOAP/XML or REST/JSON (or any other combination) is that the process you are supporting wants to be informed in real-time or wants to execute actions in real-time without any support from the integration. In other words, you want the application to push the requests to eMagiz instead of eMagiz having to pull the data out of an application.
36
37 In this microlearning, we will focus on the REST web service and how you can host this in eMagiz through some simple steps.
38 To summarize, hosting a REST web service gives you:
39
40 * A way to listen for messages instead of actively needing to pull them.
41 * A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)
42
43 Before we delve into the steps required to configure a REST Webservice let us first turn our attention to the Best Practices when configuring a REST Webservice
44
45 === 3.1 Best practices ===
46
47 * Don’t change your process when executing Capture and Design. Those steps don’t change if you want the output of what is being delivered on your REST endpoint transformed to a CDM and beyond
48 * Use naming conventions to make it clear to the calling party what the build-up of the endpoint is, which methods are allowed and which content types are allowed
49 * Keep the connectivity in the entry and the transformation in the onramp
50 * Use one HTTP Inbound Gateway per HTTP Operation (i.e. GET /order/{uuid} or POST /order)
51
52 === 3.3 Setting up Capture & Design ===
53
54 As with all solutions, we start our journey in Capture and from there we move through the various ILM phases of eMagiz.
55 In Capture you need to, just as with other solutions check whether the system already exists and if not create a new system.
56 Subsequently, you draw the lines and fill in the relevant information.
57
58 In the Design phase, there is one deviation from the standard approach in Design. And that deviation is that you need to select the option called Combined Entry Connector on the system level.
59
60 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--combined-entry-connector.png]]
61
62 After you have selected this option you need to select the option Custom as Entry Connector Type
63
64 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--combined-entry-connector-type.png]]
65
66 === 3.2 Configuring the server ===
67
68 The first part of the solution in Create is configuring the server that will host all endpoints.
69 By configuring the server you will give yourself the option to publish certain endpoints (one per HTTP Inbound Gateway).
70
71 Because you want to host all endpoints on _one_ server this part of the configuration only needs to be executed once.
72
73 To create the server you need a support object called Jetty Server
74
75 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--jetty-server.png]]
76
77 After you have added the Jetty Server to the canvas you can open it and fill in the details.
78
79 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--jetty-server-starting-point.png]]
80
81 The first step is to select a connector. When running in AWS or if you want to handle the authentication without a client certificate requirement the Select channel connector is the option of your choice. In most cases, this is used
82 In the pop-up that follows you need to fill in the port (with the help of a property)
83
84 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--edit-server-connector.png]]
85
86 After you have done this you need to select the handler type. Always choose the option Servlet context handler (unless you have very strong arguments to deviate from this).
87 This will result in the following
88
89 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-context-handler-result.png]]
90
91 The next step will be to add a context path. This will become the first part of your endpoint after the host itself. You can opt for a single / or you could opt for something more specific.
92 After that, you select the option called HTTP Inbound endpoint dispatcher servlet and give it a name.
93
94 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-result.png]]
95
96 The last step of our server configuration is to select a Servlet Mapping. This is the second part of your endpoint and gives you the option to group various endpoints.
97 For example, you could use /apigateway or /messaging as such a group identifier.
98 Always ensure that with this configuration you leave yourself the possibility to differentiate between the specific operations.
99
100 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-mapping-result.png]]
101
102 The only thing left to do is to save this configuration. This concludes the first steps for successfully making endpoints available.
103
104 Based on the above configuration the endpoint will now look as follows: {{code}}http://localhost:port/microlearning/apigateway/{{/code}}
105
106 In the next part of this microlearning, we will explain which steps you need to take per operation that you want to expose to the outside world.
107
108 === 3.3 Configuring an HTTP Inbound Gateway ===
109
110 Per operation that you want to expose you need to have an HTTP Inbound Gateway as a starting point of your solution.
111 Ensure that you create two channels (one for the request and one for the response) within your solution.
112 You will need those channels as input and output of your HTTP Inbound Gateway.
113
114 The next step would be to open the HTTP Inbound Gateway and configure it accordingly
115
116 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway.png]]
117
118 At least you need to add a path that will make the endpoint specific for a certain HTTP Operation and define the HTTP Operation (POST, GET, DELETE)
119
120 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-path-operation.png]]
121
122 Furthermore, you can define settings such as params that are required or that your endpoint only consumes JSON for example to further limit the options given to clients calling the endpoint.
123
124 Apart from the settings on the Basic tab you need to set a couple of things on the Advanced tab. One of these settings is the request payload type and the error channel.
125 For the request payload, you should enter the value java.lang.String and for Error channel you should select the channel to which you want to route error messages.
126
127 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-advanced-settings.png]]
128
129 Furthermore, when you use paramaters (path or query) you can place them in the message headers with a simple SpEL expression:
130
131 * #pathVariables['{nameofpathparam}']
132 * #requestParams['{nameofqueryparam}']
133
134 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-parameters.png]]
135
136 Based on the above configuration the endpoint will now look as follows: {{code}}http://localhost:port/microlearning/apigateway/demo{{/code}}
137
138 === 3.4 Error Handling ===
139
140 **Returning a 401**
141 In case you secure the web service with the help of an ApiKey you can validate whether what the client sends to the web service for authentication is indeed a correct ApiKey. This can be done via the following steps:
142
143 * Place a standard filter in your entry to validate if the ApiKey provided by the client is valid. This can be done via a SpEL expression comparable to the following SpEL expression {{code language="spel"}}headers['Authorization'] == '${authentication.inbound.api-key}'{{/code}}
144 * In cases where the client is not authorized lead the message back to a standard header enricher. In this standard header, enricher add a header called http_statusCode with a value of 401
145 * Add a standard transformer to set a default message that can be given back to the client. An example would be {{code language="xml"}}{ "errors": [{ "internalMessage": "Unauthorized" }]}{{/code}}.
146
147 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-401.png]]
148
149 **Returning a 403**
150 In case you have secured your REST web service with the help of a client certificate and the client is unable to provide the correct certificate eMagiz will return a 403 by default. No other changes in the flow are needed
151
152 **Returning a 404**
153 eMagiz will give back a 404 by default if the endpoint is not configured in one of the HTTP inbound channel adapters in your flow. You can override this functionality via the following steps.
154
155 * Add a separate HTTP inbound channel adapter that resolves to /\* (this catches everything that cannot be resolved by any other HTTP inbound channel adapter)
156 * Set a standard header enricher and add a header called http_statusCode with a value 404
157 * Add a standard transformer to set a default message that can be given back to the client. An example would be {{code language="xml"}}{ "errors": [{ "internalMessage": "Het aangeroepen endpoint is niet gevonden" }]}{{/code}}.
158
159 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-404.png]]
160
161 **Returning a 500**
162 eMagiz will give back a 500 by default if the flow results in an unresolvable error. To counteract this for most scenarios the error handling in eMagiz for synchronous flows has changed in such a way that the message or error will be given back to the client. To specify the HTTP code and body of the response you can follow these steps.
163 * Use the standard filter eMagiz gives you in a synchronous flow (with the SpEL expression {{code language="spel"}}headers['emagiz_error_isErrorMessage']!=true{{/code}}) and make sure that instead of throwing a default error the error channel leads to a standard header enricher
164 * Set a standard header enricher and add a header called http_statusCode with a value of 500
165 * Add a standard transformer to set a default message that can be given back to the client. An example would be {{code language="xml"}}{ "errors": [{ "internalMessage": "Een technische error heeft plaatsgevonden in de integratie" }]}{{/code}}.
166
167 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-500.png]]
168
169 == 4. Key takeaways ==
170
171 * The application (client) pushes the data to eMagiz
172 * To summarize, hosting a REST web service gives you:
173 ** A way to listen for messages instead of actively needing to pull them.
174 ** A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)
175 * Error handling can be modeled out
176
177 == 5. Suggested Additional Readings ==
178
179 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
180
181 )))((({{toc/}}))){{/container}}{{/container}}