Configuration REST web service

{{container}}{{container layoutStyle="columns"}}(((

In this microlearning, we will discuss how you can manually host a REST web service outside the API management layer of eMagiz.

3

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.

4

5

In this microlearning, we will focus on the REST web service and how you can host this in eMagiz through some simple steps.

6

To summarize, hosting a REST web service gives you:

7

8

* A way to listen for messages instead of actively needing to pull them.

9

* A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)

10

11

Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].

12

13

== 1. Prerequisites ==

14

15

* Intermediate knowledge of the eMagiz platform

16

17

== 2. Key concepts ==

18

19

This microlearning centers around configuring a REST web service.

20

With configuration, we mean: The steps you need to execute to achieve a certain result

21

With REST, we mean: A web service that adheres to the RESTful principles

22

23

* The application (client) pushes the data to eMagiz

24

* To summarize, hosting a REST web service gives you:

25

** A way to listen for messages instead of actively needing to pull them.

26

** A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)

27

28

== 3. Configuration REST web service ==

29

30

In this microlearning, we will discuss how you can manually host a REST web service outside the API management layer of eMagiz.

31

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.

32

33

In this microlearning, we will focus on the REST web service and how you can host this in eMagiz through some simple steps.

34

To summarize, hosting a REST web service gives you:

35

36

* A way to listen for messages instead of actively needing to pull them.

37

* A way to receive messages via various HTTP methods (GET, PUT, POST, DELETE, etc.)

38

39

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

40

41

=== 3.1 Best practices ===

42

43

* 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

44

* 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

45

* Keep the connectivity in the entry and the transformation in the onramp

46

* Use one HTTP Inbound Gateway per HTTP Operation (i.e. GET /order/{uuid} or POST /order)

47

48

=== 3.3 Setting up Capture & Design ===

49

50

As with all solutions, we start our journey in Capture and from there we move through the various ILM phases of eMagiz.

51

In Capture you need to, just as with other solutions check whether the system already exists and if not create a new system.

52

Subsequently, you draw the lines and fill in the relevant information.

53

54

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.

55

56

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--combined-entry-connector.png]]

57

58

After you have selected this option you need to select the option Custom as Entry Connector Type

59

60

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--combined-entry-connector-type.png]]

61

62

=== 3.2 Configuring the server ===

63

64

The first part of the solution in Create is configuring the server that will host all endpoints.

65

By configuring the server you will give yourself the option to publish certain endpoints (one per HTTP Inbound Gateway).

66

67

Because you want to host all endpoints on _one_ server this part of the configuration only needs to be executed once.

68

69

To create the server you need a support object called Jetty Server

70

71

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--jetty-server.png]]

72

73

After you have added the Jetty Server to the canvas you can open it and fill in the details.

74

75

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--jetty-server-starting-point.png]]

76

77

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

78

In the pop-up that follows you need to fill in the port (with the help of a property)

79

80

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--edit-server-connector.png]]

81

82

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).

83

This will result in the following

84

85

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-context-handler-result.png]]

86

87

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.

88

After that, you select the option called HTTP Inbound endpoint dispatcher servlet and give it a name.

89

90

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-result.png]]

91

92

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.

93

For example, you could use /apigateway or /messaging as such a group identifier.

94

Always ensure that with this configuration you leave yourself the possibility to differentiate between the specific operations.

95

96

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--servlet-mapping-result.png]]

97

98

The only thing left to do is to save this configuration. This concludes the first steps for successfully making endpoints available.

99

100

Based on the above configuration the endpoint will now look as follows: http://localhost:port/microlearning/apigateway/\*

101

102

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.

103

104

=== 3.3 Configuring an HTTP Inbound Gateway ===

105

106

Per operation that you want to expose you need to have an HTTP Inbound Gateway as a starting point of your solution.

107

Ensure that you create two channels (one for the request and one for the response) within your solution.

108

You will need those channels as input and output of your HTTP Inbound Gateway.

109

110

The next step would be to open the HTTP Inbound Gateway and configure it accordingly

111

112

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway.png]]

113

114

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)

115

116

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-path-operation.png]]

117

118

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.

119

120

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.

121

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.

122

123

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-advanced-settings.png]]

124

125

Furthermore, when you use paramaters (path or query) you can place them in the message headers with a simple SpEL expression:

126

127

* #pathVariables['{nameofpathparam}']

128

* #requestParams['{nameofqueryparam}']

129

130

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--http-inbound-gateway-parameters.png]]

131

132

Based on the above configuration the endpoint will now look as follows: http://localhost:port/microlearning/apigateway/demo

133

134

=== 3.4 Error Handling ===

135

136

**Returning a 401**

137

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:

138

139

* 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 (headers['Authorization'] == '${authentication.inbound.api-key}')

140

* 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

141

* Add a standard transformer to set a default message that can be given back to the client. An example would be '{ "errors": [{ "internalMessage": "Unauthorized" }]}'.

142

143

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-401.png]]

144

145

**Returning a 403**

146

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

147

148

**Returning a 404**

149

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.

150

151

* Add a separate HTTP inbound channel adapter that resolves to /\* (this catches everything that cannot be resolved by any other HTTP inbound channel adapter)

152

* Set a standard header enricher and add a header called http_statusCode with a value 404

153

* Add a standard transformer to set a default message that can be given back to the client. An example would be '{ "errors": [{ "internalMessage": "Het aangeroepen endpoint is niet gevonden" }]}’.

154

155

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-404.png]]

156

157

**Returning a 500**

158

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.

159

* Use the standard filter eMagiz gives you in a synchronous flow (with the SpEL expression headers['emagiz_error_isErrorMessage']!=true) and make sure that instead of throwing a default error the error channel leads to a standard header enricher

160

* Set a standard header enricher and add a header called http_statusCode with a value of 500

161

* Add a standard transformer to set a default message that can be given back to the client. An example would be '{ "errors": [{ "internalMessage": "Een technische error heeft plaatsgevonden in de integratie" }]}’.

162

163

[[image:Main.Images.Microlearning.WebHome@intermediate-rest-webservice-connectivity-configuration--service-500.png]]

== 4. Assignment ==

Navigate to a flow within your (Academy) project and configure a REST Webservice that eMagiz will host without worrying about error handling and authentication.

168

In this REST Webservice expose the POST operation on the following endpoint: http://localhost:port/microlearning/apigateway/demo

169

This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.

170

171

== 5. Key takeaways ==

172

173

* The application (client) pushes the data to eMagiz

174

* To summarize, hosting a REST web service gives you: