Last modified by Erik Bakker on 2023/04/14 08:19
Show last authors
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 Each request executed by the client will return a success or a failure response.
33
34 === 3.1 Success ===
35 The default response code eMagiz uses for a Success is a 200 HTTP Status Code that could be accompanied by a response body.
36 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.
37
38 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.
39
40 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--default-success-response.png]]
41
42 {{info}}Note that when the backend operation returns another HTTP status code that differs from the default 200 eMagiz generates it is prudent to change the default status code accordingly.{{/info}}
43
44 === 3.2 Failure ===
45 When we zoom in on the cases where something fails we have to discern multiple scenarios:
46 * Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
47 * Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
48 * eMagiz receives a specific error from the backend operation or something goes wrong in transit -> eMagiz will return a 500 Internal Error
49 * eMagiz does not receive a response from the backend -> eMagiz will return a 504 Timeout Error
50 * A validation error occurs -> eMagiz will return a 422 Validation Error
51
52 === 3.3 Control the information ===
53 Apart from giving back the response codes to the client eMagiz, on default also returns the payload the moment things went wrong. From a technical perspective very handy to have, however it is not always as informative for the client calling the API operation.
54
55 As a result eMagiz auto-generates specific status codes for the three most likely scenarios that occur (422,500,504) but also provides you with the option to redefine the error handling to your own liking. 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
56
57 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--control-error-message.png]]
58
59 Here you see what eMagiz has created for you on default. By pressing the Edit button on either one of them you can change things like the HTTP code you want to return and the payload you want to return when this happens.
60
61 Furthermore you can add additional response codes including the response body. To do so press the button "New".
62
63 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-error-handling-from-a-client-perspective--create-additional-possible-responses.png]]
64
65 In the pop-up that follows you can specify the HTTP Status Code response, define the body of the message and the message type of the response
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. Key takeaways ==
86
87 * Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
88 * Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
89 * eMagiz receives a specific error from the backend operation or something goes wrong in transit -> eMagiz will return a 500 Internal Error
90 * eMagiz does not receive a response from the backend -> eMagiz will return a 504 Timeout Error
91 * A validation error occurs -> eMagiz will return a 422 Validation Error
92 * eMagiz also writes errors to the log for monitoring and alerting
93 * You can control the information the client receives in case of an error
94
95 == 5. Suggested Additional Readings ==
96
97 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:
98
99 * [[REST API - Error Handling>>https://www.baeldung.com/rest-api-error-handling-best-practices||target="blank"]]
100
101 )))((({{toc/}}))){{/container}}{{/container}}