Error Handling from a Client Perspective

(((

In this microlearning, we will focus on understanding how the error handling for the API Gateway works in a general sense.

5

As the API Gateway is synchronous you will get a response for every request you have executed. This works for both OK and NOT OK responses

6

7

Therefore the error handling is created in such a way that the client gets told if the response was OK or NOT OK

8

9

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

10

11

== 1. Prerequisites ==

12

* Basic knowledge of the eMagiz platform

13

14

== 2. Key concepts ==

15

This microlearning centers around error handling from a client perspective for the API Gateway solution of eMagiz.

16

With error handling we mean: Handling the NOT OK responses that occur in transit between API Gateway and backend operation or NOT OK response received from the backend operation

17

With client perspective we mean: How should I interpret the response from the API Gateway to determine success or failure

18

With API Gateway we mean: A collection of RESTful API operations that can be published to the outside world to give them access to applications that are linked to your business process

19

20

The eMagiz API Gateway will always give back HTTP Response codes along the following lines:

21

22

* 100-level (Informational) — Server acknowledges a request

23

* 200-level (Success) — Server completed the request as expected

24

* 300-level (Redirection) — The client needs to perform further actions to complete the request

25

* 400-level (Client error) — The client sent an invalid request

26

* 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server

27

28

Of these levels, the 200-level for Success calls and the 400-level and 500-level are most frequently used within the context of eMagiz.

29

30

== 3. Error Handling from a Client Perspective ==

31

32

The eMagiz API Gateway will always give back HTTP Response codes along the following lines:

33

34

* 100-level (Informational) — Server acknowledges a request

35

* 200-level (Success) — Server completed the request as expected

36

* 300-level (Redirection) — The client needs to perform further actions to complete the request

37

* 400-level (Client error) — The client sent an invalid request

38

* 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server

39

40

Of these levels, the 200-level for Success calls and the 400-level and 500-level for Unsuccesfull calls are most frequently used within the context of eMagiz.

41

Each request executed by the client can return a Success or a Failure.

42

43

=== 3.1 Success ===

44

The default response code eMagiz uses for a Success is a 200 HTTP Status Code that could be accompanied by a response body.

45

If the backend operation uses a 201 for example to indicate the creation of a resource in the backend eMagiz will give this back to the client making the request.

46

47

So in general terms eMagiz gives the status code back to the client that itself has received from the backend operation that is called by eMagiz.

48

49

=== 3.2 Failure ===

50

When we zoom in on the cases where something fails we have to discern multiple scenarios:

51

* Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found

52

* Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized

53

* eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.

54

* eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error

55

* Something goes wrong in transit -> eMagiz will return a 500 Internal Error

56

57

=== 3.3 Control the information ===

58

Apart from giving back the response codes to the client eMagiz, on default also returns the payload the moment things went wrong.

59

You can imagine that doing that is not the ideal situation. Therefore eMagiz provides you with the option to define how you handle these specific errors.

60

61

To do so navigate to Design and open the catalog. In the catalog select the operation for which you want to configure this and select the tab Responses

62

63

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--control-error-message.png]]

64

65

On this screen, you can select the button New. In the pop-up that follows you can specify the HTTP Status Code response and define the body of the message

66

67

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--set-response-code.png]]

68

69

To get even more control you can assign standard occurrences of errors while in transit to a certain HTTP Status Code. You can do so by pressing New under Custom Error Handler

70

71

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler.png]]

72

73

Select the type, fill in the remainder of the details, and press Save. After you have updated your all entry and deployed it this new functionality will be in effect.

74

75

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler-type.png]]

76

77

=== 3.4 eMagiz Monitoring ===

78

79

Apart from sending the response back to the client eMagiz will also write a warning to the log the moment something goes wrong after eMagiz has accepted the request.

80

This means that cases such a the 404 and 401 do not show up here and should be dealt with by the client exclusively.

81

82

In the other scenarios where eMagiz has (attempted to) send data to a backend operation and something fails eMagiz will write a warning to the log.

83

On this warning, you can set up alerts for (pro-active) monitoring

== 4. Assignment ==

Try to call an endpoint of the API Gateway while not being authorized to see how the error handling of eMagiz works.

88

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

89

90

== 5. Key takeaways ==

91

92

* Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found

93

* Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized

94

* eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.

95

* eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error

96

* Something goes wrong in transit -> eMagiz will return a 500 Internal Error

97

* eMagiz also writes errors to the log for monitoring and alerting

98

* You can control the information the client receives in case of an error

99

100

== 6. Suggested Additional Readings ==

101

102

If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following link:

103

104

* https://www.baeldung.com/rest-api-error-handling-best-practices

105

106

== 7. Silent demonstration video ==

107

108

This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned. Disclaimer, you only see the eMagiz part but if you follow the above steps you are good to go!

109

110

{{video attachment="crashcourse-api-gateway-error-handling-from-a-client-perspective.mp4" reference="Main.Videos.Microlearning.WebHome"/}}

111

112

)))((({{toc/}}))){{/container}}{{/container}}

author	version	line-number	content
		1	{{container}}
		2	{{container layoutStyle="columns"}}
		3	(((
		4	In this microlearning, we will focus on understanding how the error handling for the API Gateway works in a general sense.
		5	As the API Gateway is synchronous you will get a response for every request you have executed. This works for both OK and NOT OK responses
		6
		7	Therefore the error handling is created in such a way that the client gets told if the response was OK or NOT OK
		8
		9	Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
		10
		11	== 1. Prerequisites ==
		12	* Basic knowledge of the eMagiz platform
		13
		14	== 2. Key concepts ==
		15	This microlearning centers around error handling from a client perspective for the API Gateway solution of eMagiz.
		16	With error handling we mean: Handling the NOT OK responses that occur in transit between API Gateway and backend operation or NOT OK response received from the backend operation
		17	With client perspective we mean: How should I interpret the response from the API Gateway to determine success or failure
		18	With API Gateway we mean: A collection of RESTful API operations that can be published to the outside world to give them access to applications that are linked to your business process
		19
		20	The eMagiz API Gateway will always give back HTTP Response codes along the following lines:
		21
		22	* 100-level (Informational) — Server acknowledges a request
		23	* 200-level (Success) — Server completed the request as expected
		24	* 300-level (Redirection) — The client needs to perform further actions to complete the request
		25	* 400-level (Client error) — The client sent an invalid request
		26	* 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server
		27
		28	Of these levels, the 200-level for Success calls and the 400-level and 500-level are most frequently used within the context of eMagiz.
		29
		30	== 3. Error Handling from a Client Perspective ==
		31
		32	The eMagiz API Gateway will always give back HTTP Response codes along the following lines:
		33
		34	* 100-level (Informational) — Server acknowledges a request
		35	* 200-level (Success) — Server completed the request as expected
		36	* 300-level (Redirection) — The client needs to perform further actions to complete the request
		37	* 400-level (Client error) — The client sent an invalid request
		38	* 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server
		39
		40	Of these levels, the 200-level for Success calls and the 400-level and 500-level for Unsuccesfull calls are most frequently used within the context of eMagiz.
		41	Each request executed by the client can return a Success or a Failure.
		42
		43	=== 3.1 Success ===
		44	The default response code eMagiz uses for a Success is a 200 HTTP Status Code that could be accompanied by a response body.
		45	If the backend operation uses a 201 for example to indicate the creation of a resource in the backend eMagiz will give this back to the client making the request.
		46
		47	So in general terms eMagiz gives the status code back to the client that itself has received from the backend operation that is called by eMagiz.
		48
		49	=== 3.2 Failure ===
		50	When we zoom in on the cases where something fails we have to discern multiple scenarios:
		51	* Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
		52	* Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
		53	* eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.
		54	* eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error
		55	* Something goes wrong in transit -> eMagiz will return a 500 Internal Error
		56
		57	=== 3.3 Control the information ===
		58	Apart from giving back the response codes to the client eMagiz, on default also returns the payload the moment things went wrong.
		59	You can imagine that doing that is not the ideal situation. Therefore eMagiz provides you with the option to define how you handle these specific errors.
		60
		61	To do so navigate to Design and open the catalog. In the catalog select the operation for which you want to configure this and select the tab Responses
		62
		63	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--control-error-message.png]]
		64
		65	On this screen, you can select the button New. In the pop-up that follows you can specify the HTTP Status Code response and define the body of the message
		66
		67	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--set-response-code.png]]
		68
		69	To get even more control you can assign standard occurrences of errors while in transit to a certain HTTP Status Code. You can do so by pressing New under Custom Error Handler
		70
		71	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler.png]]
		72
		73	Select the type, fill in the remainder of the details, and press Save. After you have updated your all entry and deployed it this new functionality will be in effect.
		74
		75	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler-type.png]]
		76
		77	=== 3.4 eMagiz Monitoring ===
		78
		79	Apart from sending the response back to the client eMagiz will also write a warning to the log the moment something goes wrong after eMagiz has accepted the request.
		80	This means that cases such a the 404 and 401 do not show up here and should be dealt with by the client exclusively.
		81
		82	In the other scenarios where eMagiz has (attempted to) send data to a backend operation and something fails eMagiz will write a warning to the log.
		83	On this warning, you can set up alerts for (pro-active) monitoring
		84
		85	== 4. Assignment ==
		86
		87	Try to call an endpoint of the API Gateway while not being authorized to see how the error handling of eMagiz works.
		88	This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
		89
		90	== 5. Key takeaways ==
		91
		92	* Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
		93	* Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
		94	* eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.
		95	* eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error
		96	* Something goes wrong in transit -> eMagiz will return a 500 Internal Error
		97	* eMagiz also writes errors to the log for monitoring and alerting
		98	* You can control the information the client receives in case of an error
		99
		100	== 6. Suggested Additional Readings ==
		101
		102	If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following link:
		103
		104	* https://www.baeldung.com/rest-api-error-handling-best-practices
		105
		106	== 7. Silent demonstration video ==
		107
		108	This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned. Disclaimer, you only see the eMagiz part but if you follow the above steps you are good to go!
		109
		110	{{video attachment="crashcourse-api-gateway-error-handling-from-a-client-perspective.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
		111
		112	)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Error Handling from a Client Perspective