Skip to Content

Wiki source code of Configuration REST web service

Last modified by Waria on 2026/09/03 10:20
Show last authors
1 {{container}}
2 {{container layoutStyle="columns"}}
3 (((
4 In this microlearning session, we will explore how to manually host a REST web service outside of eMagiz's API management layer. By the end, you will understand the steps required to configure a REST service, including best practices and key concepts, and how to handle various HTTP operations and errors effectively.
5
6 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
7
8 == 1. Prerequisites ==
9
10 * Intermediate knowledge of the eMagiz platform
11
12 == 2. Key concepts ==
13
14 This microlearning centers around configuring a REST web service.
15
16 * With configuration, we mean: The steps you need to execute to achieve a specific result.
17 * With REST, we mean: A web service that adheres to the RESTful principles.
18 * The application (client) pushes the data to eMagiz.
19
20 == 3. Configuration REST web service ==
21
22 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.
23
24 In this microlearning, we will focus on the REST web service and how you can host this in eMagiz through some simple steps. To summarize, hosting a REST web service gives you the following:
25
26 * A way to listen for messages instead of actively needing to pull them.
27 * A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, and others)
28
29 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
30
31 === 3.1 Best practices ===
32
33 * Remember to fill in Capture and Design as you are used to. 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
34 * 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
35 * Keep the connectivity in the entry and the transformation in the onramp
36 * Use one HTTP Inbound Gateway per HTTP Operation (i.e. GET /order/{uuid} or POST /order)
37
38 === 3.2 Setting up Capture & Design ===
39
40 As with all solutions, we start our journey in Capture, and from there, we move through the various ILM phases of eMagiz.
41 In Capture, you need to, just as with other solutions, check whether the system already exists and, if not, create a new system.
42 Subsequently, you draw the lines and fill in the relevant information.
43
44 Subsequently, in the Design phase, you execute all regular steps as you are used to when creating a new system or a new integration.
45
46 === 3.3 Setting the HTTP Security on infra level ===
47
48 The first part of the solution in Create is configuring the HTTP security. This is done in the infra flow. To ensure that the HTTP security in the new 3rd generation runtime works as before, you need to add a support object of the type "HTTP Security." In this "HTTP Security" support object, you only need to define "Disabled" in the Security drop-down.
49
50 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--add-http-security-rest-generation-three.png]]
51
52 When you have added this to the infra flow of the corresponding entry, you can create a new version and open the entry that you just added to Create. In this entry, you need to add an HTTP inbound gateway in which you define your endpoint. This is explained below.
53
54 === 3.4 Configuring an HTTP Inbound Gateway ===
55
56 Per operation that you want to expose, you need to have an HTTP Inbound Gateway as a starting point of your solution.
57 Ensure that you create two channels (one for the request and one for the response) within your solution.
58 You will need those channels as input and output of your HTTP Inbound Gateway.
59
60 The next step would be to open the HTTP Inbound Gateway and configure it accordingly.
61
62 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway.png]]
63
64 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)
65
66 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-path-operation.png]]
67
68 Furthermore, you can define settings such as required params or that your endpoint only consumes JSON, for example, to further limit the options given to clients calling the endpoint.
69
70 Apart from the settings on the Basic tab, you need to set a few things on the Advanced tab. One of these settings is the request payload type and the error channel.
71 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.
72
73 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-advanced-settings.png]]
74
75 Furthermore, when you use parameters (path or query), you can place them in the message headers with a simple SpEL expression:
76
77 * #pathVariables['{nameofpathparam}']
78 * #requestParams['{nameofqueryparam}']
79
80 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-parameters.png]]
81
82 Based on the above configuration, the endpoint will now look as follows:
83
84 {{code}}
85 http://localhost:port/microlearning/rest/demo
86 {{/code}}
87
88 === 3.5 Error Handling ===
89
90 **Returning a 401**
91 In case you secure the web service with the help of an API key, 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:
92
93 * 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}}
94 * 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
95 * Add a standard transformer to set a default message that can be returned to the client. An example would be {{code language="xml"}}{ "errors": [{ "internalMessage": "Unauthorized" }]}{{/code}}.
96
97 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-401.png]]
98
99 **Returning a 403**
100 If you have secured your REST web service with the help of a client certificate and the client cannot provide the correct certificate, eMagiz will return a 403 by default. No other changes in the flow are needed.
101
102 **Returning a 404**
103 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.
104
105 * Add a separate HTTP inbound channel adapter that resolves to /\* (this catches everything that any other HTTP inbound channel adapter cannot resolve)
106 * Set a standard header enricher and add a header called http_statusCode with a value of 404
107 * Add a standard transformer to set a default message that can be returned to the client. An example would be {{code language=" xml"}}{"errors": [{"internal message": "Het aangeroepen endpoint is niet gevonden"}]}{{/code}}.
108
109 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-404.png]]
110
111 **Returning a 500**
112 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 so that the message or error will be returned to the client. To specify the HTTP code and body of the response, you can follow these steps.
113
114 * 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
115 * Set a standard header enricher and add a header called http_statusCode with a value of 500
116 * Add a standard transformer to set a default message that can be returned to the client. An example would be {{code language="xml"}}{ "errors": [{ "internalMessage": "Een technische error heeft plaatsgevonden in de integratie" }]}{{/code}}.
117
118 [[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-500.png]]
119
120 === 3.6 Define the Runtime Settings ===
121
122 After configuring everything in Create, you must define the runtime settings under Deploy -> Architecture. This new functionality allows you to specify the port on which the REST web service needs to be running (and optionally SSL settings when running it on-premise). You can access these settings via the context menu on the runtime level.
123
124 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-context-menu.png]]
125
126 Once you have selected this option, a pop-up will appear, showing you, among others, the HTTP settings. The HTTP enabled option needs to be enabled for a REST web service, and when we look at the advanced tab, we need a reference to the port we will use here (which can be a property reference).
127
128 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-default.png]]
129
130 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--http-settings-default-config.png]]
131
132 {{info}}
133 If you want to learn more about the runtime settings options in general, please check out this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Runtime Management.intermediate-emagiz-runtime-management-runtime-settings.WebHome||target="blank"]]
134 {{/info}}
135
136 === 3.6 Check your route settings ===
137
138 For cloud-hosted endpoints, you are already used to defining a [[route>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.intermediate-emagiz-cloud-management-routes||target="blank"]] configuration for your endpoints.
139
140
141 {{info}}
142 An example of your endpoint following the configuration above woudl be: {{code}}https://example+dns+label-cloud001.emagizcloud.com/microlearning/rest/demo{{/code}}
143 {{/info}}
144
145
146 {{warning}}
147 This step is only relevant when running your solution on-premise
148 {{/warning}}
149
150 With the 3rd generation runtime, you must also do this for your on-premise hosted endpoints. When configuring the route, you need to take the following into account:
151
152 * The port configured under the route must match the port defined under the Runtime settings configuration
153 * The DNS left-most label has no effect and can be filled with anything
154 * Make sure to link the correct container to your route
155
156 [[image:Main.Images.Migrationpath.WebHome@migration-path-migration-path-emagiz-runtime-generation-3--route-config-on-prem.png]]
157
158 == 4. Key takeaways ==
159
160 * A REST web service allows the application (client) to push data to eMagiz in real-time, reducing the need for the platform to pull data actively.
161 * Hosting a REST web service provides flexibility in receiving messages via different HTTP methods, such as GET, POST, PUT, DELETE, and more.
162 * Ensure that you follow best practices like maintaining clear endpoint naming conventions and handling security configurations effectively.
163 * Proper error handling modeling is essential, with specific strategies for managing different HTTP status codes, including 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), and 500 (Internal Server Error).
164
165 == 5. Suggested Additional Readings ==
166
167 If you are interested in this topic and want more information, please read the help text provided by eMagiz and read the following links:
168
169 * [[eMagiz Support (Menu)>>doc:Main.eMagiz Support.WebHome||target="blank"]]
170 ** [[Migration Paths (Navigation)>>doc:Main.eMagiz Support.Migration Paths.WebHome||target="blank"]]
171 *** [[Hosting a REST web service (Explanation)>>doc:Main.eMagiz Support.Migration Paths.migration-path-host-rest-webservice-runtime-generation-3||target="blank"]]
172 * [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]
173 ** [[Crash Course API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]
174 *** [[Parameters (Path, Query) (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-parameters||target="blank"]]
175 * [[Intermediate (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]
176 ** [[eMagiz Cloud Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.WebHome||target="blank"]]
177 *** [[Routes (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.intermediate-emagiz-cloud-management-routes||target="blank"]]
178 * [[Host REST web service (Search Results)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22host+REST+web+service%22||target="blank"]]
179 )))
180
181 (((
182 {{toc/}}
183 )))
184 {{/container}}
185 {{/container}}