Skip to Content
Version 1.1 by eMagiz on 2022/05/05 16:37
Show last authors
1 {{html wiki="true"}}
2 <div class="ez-academy">
3 <div class="ez-academy_body">
4
5
6 <li class="doc-nav__item"><a href="../../docs/microlearning/crashcourse-api-gateway-index" class="doc-nav__link">Home</a></li>
7
8
9
10
11
12
13 <div class="doc">
14
15
16
17 = Error Handling from a Client Perspective =
18
19 In this microlearning, we will focus on understanding how the error handling for the API Gateway works in a general sense.
20 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
21
22 Therefore the error handling is created in such a way that the client gets told if the response was OK or NOT OK
23
24 Should you have any questions, please contact academy@emagiz.com.
25
26 * Last update: February 19th, 2021
27 * Required reading time: 7 minutes
28
29 == 1. Prerequisites ==
30 * Basic knowledge of the eMagiz platform
31
32 == 2. Key concepts ==
33 This microlearning centers around error handling from a client perspective for the API Gateway solution of eMagiz.
34 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
35 With client perspective we mean: How should I interpret the response from the API Gateway to determine success or failure
36 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
37
38 The eMagiz API Gateway will always give back HTTP Response codes along the following lines:
39
40 * 100-level (Informational) — Server acknowledges a request
41 * 200-level (Success) — Server completed the request as expected
42 * 300-level (Redirection) — The client needs to perform further actions to complete the request
43 * 400-level (Client error) — The client sent an invalid request
44 * 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server
45
46 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.
47
48
49
50 == 3. Error Handling from a Client Perspective ==
51
52 The eMagiz API Gateway will always give back HTTP Response codes along the following lines:
53
54 * 100-level (Informational) — Server acknowledges a request
55 * 200-level (Success) — Server completed the request as expected
56 * 300-level (Redirection) — The client needs to perform further actions to complete the request
57 * 400-level (Client error) — The client sent an invalid request
58 * 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server
59
60 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.
61 Each request executed by the client can return a Success or a Failure.
62
63 === 3.1 Success ===
64 The default response code eMagiz uses for a Success is a 200 HTTP Status Code that could be accompanied by a response body.
65 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.
66
67 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.
68
69 === 3.2 Failure ===
70 When we zoom in on the cases where something fails we have to discern multiple scenarios:
71 * Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
72 * Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
73 * eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.
74 * eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error
75 * Something goes wrong in transit -> eMagiz will return a 500 Internal Error
76
77 === 3.3 Control the information ===
78 Apart from giving back the response codes to the client eMagiz, on default also returns the payload the moment things went wrong.
79 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.
80
81 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
82
83 <p align="center">[[image:crashcourse-api-gateway-error-handling-from-a-client-perspective--control-error-message.png||]]</p>
84
85 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
86
87 <p align="center">[[image:crashcourse-api-gateway-error-handling-from-a-client-perspective--set-response-code.png||]]</p>
88
89 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
90
91 <p align="center">[[image:crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler.png||]]</p>
92
93 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.
94
95 <p align="center">[[image:crashcourse-api-gateway-error-handling-from-a-client-perspective--custom-error-handler-type.png||]]</p>
96
97 === 3.4 eMagiz Monitoring ===
98
99 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.
100 This means that cases such a the 404 and 401 do not show up here and should be dealt with by the client exclusively.
101
102 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.
103 On this warning, you can set up alerts for (pro-active) monitoring
104
105 Each backend operation has a specific exit gate that will handle all incoming traffic, connect to the backend operation and send the response back to the client that is calling the API.
106 The exit gate can process up to five calls at the same time. The moment the response is delivered to client 1, the exit gate will continue with the message of client 6.
107
108 With this setting, we already scale the API Gateway in such a way that it can handle concurrency and peaks in traffic. For most use cases these settings will suffice.
109
110 eMagiz will generate almost everything for you when you transfer an API integration to Create.
111 There are however some things you need to change depending on the choices made in Design and based on the required authentication method.
112
113 In case you have a passthrough case and the authentication method can be handled via a REST template (i.e. basic, OAuth, azure) you only need to configure this specific authentication mechanism.
114
115 In case you have a passthrough case and the authentication cannot be handled via a REST template you need to set up the authentication yourself.
116
117 In case you have a transformation case you need to configure the outbound component + the accompanying authentication.
118
119 In the most standard case, eMagiz will auto-generate the following flow for you
120
121 <p align="center">[[image:crashcourse-api-gateway-configure-exit-gate--auto-generated-flow.png||]]</p>
122
123 Just as with the entry gate we try to auto-generate as much as possible to make your life easier the moment you start in the Create phase.
124
125 ===== Practice =====
126
127 == 4. Assignment ==
128
129 Try to call an endpoint of the API Gateway while not being authorized to see how the error handling of eMagiz works.
130 This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
131
132 == 5. Key takeaways ==
133
134 * Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
135 * Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
136 * eMagiz receives a specific error from the backend operation -> eMagiz will return the HTTP Status Code it received from the backend to the client.
137 * eMagiz does not receive a response from the backend -> eMagiz will return a 500 Internal Error
138 * Something goes wrong in transit -> eMagiz will return a 500 Internal Error
139 * eMagiz also writes errors to the log for monitoring and alerting
140 * You can control the information the client receives in case of an error
141
142
143
144 == 6. Suggested Additional Readings ==
145
146 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:
147
148 * https://www.baeldung.com/rest-api-error-handling-best-practices
149
150 == 7. Silent demonstration video ==
151
152 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!
153
154 <iframe width="1280" height="720" src="../../vid/microlearning/crashcourse-api-gateway-error-handling-from-a-client-perspective.mp4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
155
156 </div>
157 </main>
158 </div>
159 </div>
160 {{/html}}