Changes for page Updating your API Gateway Operations

Summary

• Page properties (3 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.eMagiz
	1	+XWiki.dfirdausy

Default language

...	...	@@ -1,0 +1,1 @@
	1	+en

Content

...	...	@@ -1,12 +1,9 @@
1	1	{{container}}{{container layoutStyle="columns"}}(((
2	2
3		-In our crash course on the API Gateway pattern, we have learned about setting up the API Gateway. However, we did not yet delve into the specifics of how to update your existing API Gateway solution. In this microlearning, we will focus on updating the Design phase of your API Gateway (and the subsequent steps) and we will focus on updating the Create phase of your API Gateway (and the subsequent steps). This to learn the impact of updates and to learn how we can achieve this.
	3	+Building on what we covered in our [[crash course>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]] about setting up the API Gateway, we will now focus on the next critical step: updating your existing API Gateway solution. In this microlearning, we will guide you through the process of updating both the design phase and the create phase of your API Gateway, and explore how these updates impact your solution.
4	4
5	5	Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6	6
7		-* Last update: June 28th, 2021
8		-* Required reading time: 6 minutes
9		-
10	10	== 1. Prerequisites ==
11	11
12	12	* Basic knowledge of the eMagiz platform
...	...	@@ -14,87 +14,101 @@
14	14	== 2. Key concepts ==
15	15
16	16	This microlearning centers around updating your API Gateway.
	14	+* By updating, we mean: changing existing software to reflect new insights or ideas that have come up during development and testing.
17	17
18		-By updating, we mean: Changing existing software to reflect new insights or ideas that have come up during development and/or testing
	16	+== 3. Updating your API Gateway Operations ==
19	19
	18	+In our [[crash course>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]] on the API Gateway pattern, we have learned about setting up the API Gateway. However, we still need to delve into how to update your existing API Gateway solution. In this microlearning, we will focus on updating the design phase of your API gateway (and the subsequent steps) and the create phase of your API gateway (and subsequent steps). This is to learn the impact of updates and how we can achieve this.
	19	+
20	20	* Updating can happen from Design
21	21	* Updating can happen from Create
22	22	* Both situations have a different impact
23	23
	24	+In the remainder of this microlearning, we will discuss both scenarios to clarify their impact.
24	24
	26	+=== 3.1 Updating from Design ===
25	25
26		-== 3. Updating your API Gateway Operations ==
	28	+After adding an integration to Create, you can change the error handling, the request and response message structure, the parameters, and more. In all these scenarios, you need to change something in the Design phase of eMagiz. The actual change in these parts of the API Gateway solutions is specified in earlier microlearnings. However, what to do after you have made those changes has yet to be discussed. In this microlearning, we will discuss that process within eMagiz. Note that this process **only** applies when the operation already exists in Create. If it does not yet exist in Create, eMagiz will create a new entry and exit gate for you based on the configuration in Design.
27	27
28		-In our crash course on the API Gateway pattern, we have learned about setting up the API Gateway. However, we did not yet delve into the specifics of how to update your existing API Gateway solution. In this microlearning, we will focus on updating the Design phase of your API Gateway (and the subsequent steps) and we will focus on updating the Create phase of your API Gateway (and the subsequent steps). This to learn the impact of updates and to learn how we can achieve this.
	30	+From our offering on the messaging pattern and how to update it in those scenarios, you can imagine that (parts of) the API Gateway flows need to be updated to reflect your changes. Depending on the exact change, the effect will be seen in the corresponding entry gate or the corresponding exit gate specific to an operation. The division can be made as follows:
29	29
30		-* Updating can happen from Design
31		-* Updating can happen from Create
32		-* Both situations have a different impact
	32	+* When you change something in the configuration of the API Gateway operation itself (e.g., path, error handling, parameters), the change will only impact the corresponding entry gate.
	33	+* When you change something in the configuration of the backend operation (i.e., endpoint, parameter, system request/response), the change will only impact the specific exit gate.
	34	+* When you change the gateway request/response message (with transformation), the change will impact **both** the entry gate and the specific exit gate.
	35	+* When you change the API Gateway's security configuration, the infra flow and all entry gates will be updated (by clicking on Update security in the context menu).
33	33
34		-In the remainder of this microlearning, we will discuss both scenarios. This to get clarity on what the impact is of both scenarios.
	37	+eMagiz will automate all changes on the entry gate level except for changing the security configuration due to the impact of such a change. When the change is executed, eMagiz will automatically create a new version of the entry gate to reflect the change. To update changes in the exit gate, you need to execute a manual version bump. This division is made because the exit gate can contain much more customization, while the entry gate is, in most cases, completely generated by eMagiz.
35	35
36		-=== 3.1 Updating from Design ===
	39	+=== 3.2 Updating from Create ===
37	37
38		-After you have already added an integration to Create you might want to change the error handling, the structure of the request and/or response message, the parameters, etc. In all these scenarios you need to change something in the Design phase of eMagiz. The actual changing of these parts of the API Gateway solutions is specified in earlier microlearnings. However, what to do after you have made those changes is not yet discussed. In this microlearning, we will discuss that process within eMagiz. Note that this process **only** applies when the operation already exists in Create. If it does not yet exist in Create eMagiz will simply add the configuration to the existing flow without changing the remainder of the all-entry.
	41	+Apart from updating your API Gateway solution in Create, you can only update parts of the API Gateway solution in Create. Here, we mainly talk about changing the gateway messages. Any other changes on the 'exit gate' level have no particular impact compared to changing parts of other flows. We discern two parts of updating a (gateway) message that you can execute in the Create phase:
39	39
40		-As you might know from our offering on the messaging pattern and how to update in those scenarios you can imagine that (parts of) the API Gateway flows need to be updated to reflect your changes. Depending on the exact change the effect will be seen in the 'all entry' or in one of the exit gates that is specific to an operation. The division can be made as follows:
	43	+* Changing the dataType (i.e., from dateTime to date)
	44	+* Changing / Adding / Deleting valid enum values
41	41
42		-* When you change something to the configuration of the API Gateway itself (i.e security, error handling, parameters) the change will **only** impact the all-entry
43		-* When you change something to the configuration of the backend operation (i.e. endpoint, parameter, system request/response) the change will **only** impact the specific exit gate
44		-* When you change the gateway request/response message (with transformation) the change will impact **both** the all-entry and the specific exit gate
	46	+In both cases, eMagiz will automatically update your Swagger definition by recreating it to reflect these changes and executing a version bump of the infra flow.
45	45
46		-In all cases, you need a version bump of the flow to which you can relate the change. For exit gates, this process is identical to when you do a version bump of any messaging flow after updating for example a CDM message or message mapping. However, when you update something on the all-entry level this becomes less simple. Because eMagiz does not only pre-configure the resources for you in Create but the complete all-entry flow you **need** a reset of the all-entry to reflect these changes. To reset a flow simply access the context menu on flow level in Create (via a right-mouse click) and press Reset flow.
	48	+=== 3.3 Updating the Swagger UI ===
47	47
48		-[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--reset-flow-context-menu.png]]
	50	+Additionally, you can also update the Swagger UI of your API Gateway solution, so that it better informs your (external) parties to see the specifications of your API Gateway. As you have learned from the [[previous microlearning>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-swagger-ui||target="blank"]], the Swagger UI contains information on, not only Authorization, HTTP Resource Paths, and HTTP Operations, but also schemas, example messages, tags, and descriptions if defined.
49	49
50		-After you press this option eMagiz will present you with a confirmation pop-up to ensure that you are 100% sure that this is the correct flow that you want to reset. This because resetting a flow means returning to the original state.
	52	+==== 3.3.1 Edit Resource ====
51	51
52		-[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--reset-flow-warning.png]]
	54	+To have these information explicitly mentioned in your Swagger UI, then you need to define them in your API Catalog in Design. In this catalog page, you can find the resource that you want to work with. Given that your account has an edit permission in Design, then you can click "Edit" of that resource to edit its resource path, which will later be reflected in your Swagger UI (see the blue box in the two screenshots below of the Swagger UI).
53	53
54		-After you reset your all-entry eMagiz will update the following:
	56	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-resource.png]]
55	55
56		-* Swagger UI that is shown to clients via the Swagger documentation page
57		-* Parameter references
58		-* Error Handling
59		-* Many more
	58	+==== 3.3.2 Edit Operation ====
60	60
61		-This all depends on which changes you **made** on the Design level.
	60	+Next to that, when you click one of your resources in the API Catalog page, then you can also edit the "Operations" attached to that resource (see the screenshot below).
62	62
63		-=== 3.2 Updating from Create ===
	62	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-operation.png]]
64	64
65		-Apart from updating your API Gateway solution in Create, you can only update parts of the API Gateway solution in Create. Here we mainly talk about changing the gateway messages. Any other changes on the 'exit gate' level have no special impact compared to changing parts of other flows. We discern two parts of updating a (gateway) message that you can execute in the Create phase:
	64	+In this "Edit Operation" pop-up page, you can specify the HTTP method of that operation. Next to that, you can also specify the "Tags" and the "Summary" of that operation. The "Summary" here shortly describes your resource path and will be shown beside the path of your resource. Whereas, the "Tags" here will group together the operations with the same tag names in your Swagger UI. Thus, the screenshot below shows an example of "Financials" as the tag for {{code language='xml'}}/debtor/{code}{{/code}} and {{code}}/invoice{{/code}} operations (see the orange box below) along with the summaries of each of the resource paths (see the red box below).
66	66
67		-* Changing the dataType (i.e. from dateTime to date)
68		-* Adding valid enum values
	66	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--tags-summary.png]]
69	69
70		-In both cases, eMagiz will automatically update your Swagger definition and all-entry flow by recreating the swagger definition to reflect these changes and executing a version bump of the all-entry.
	68	+==== 3.3.2 Edit Parameters ====
71	71
72		-As is the case with all new versions in Create the changes will only be effectuated when you deploy your solution via the Deploy phase of eMagiz.
	70	+Still in the API Catalog page, right next to that "Operations" of that resource, you will see "Parameters", "Request", and "Responses" tabs. In the "Parameters" tab, you can specify the parameter's name (see the yellow box below), description (see the orange box below), the location of the parameter (see the blue box below), as well as whether the parameter is required or not (see the green box below).
73	73
	72	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--parameters-description.png]]
74	74
	74	+==== 3.3.3 Edit Request ====
75	75
76		-== 4. Assignment ==
	76	+Quite similar with the "Parameters" tab, in the "Request" tab of the API Catalog page, you can also specify the description and whether the request body is required in the request. The screenshot below shows how the Request "Description" is reflected in the Swagger UI.
77	77
78		-Think of three changes you want to apply to an API Gateway solution and see if you can determine which flow in Create needs an update.
79		-This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
	78	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--request-description.png]]
80	80
81		-== 5. Key takeaways ==
	80	+==== 3.3.4 Edit Responses ====
82	82
83		-* Updating can happen from Design
84		-* Updating can happen from Create
85		-* Both situations have a different impact
86		-* Adding a new operation to an existing solution does not involve a reset
87		-* Updating from Create does not involve a reset
88		-* Updating from Design involves a reset
	82	+Lastly, the "Responses" tab of the API Catalog page also allows you to specify the response description and example response (along with its "Media type") for a specific HTTPS status code. The screenshot below shows what are listed in the "Responses" tab is reflected in the Swagger UI.
89	89
	84	+[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--request-description.png]]
90	90
	86	+As is the case with all new versions in Create, the changes will only be effective when you deploy your solution via the eMagiz Deploy phase.
91	91
92		-== 6. Suggested Additional Readings ==
	88	+{{info}}To ensure that the changes to your Swagger file generated by eMagiz are shown to the end-user, the latest version of the API Gateway runtime infra flow needs to be included in the release and deployed to the correct environment.{{/info}}
93	93
94		-If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
	90	+== 4. Key takeaways ==
95	95
96		-== 7. Silent demonstration video ==
	92	+* Updates to your API Gateway can be made either during the Design phase or the Create phase, each with distinct impacts.
	93	+* Changes made in the Design phase affect the configuration of the entry gate and may necessitate updates to both entry and exit gates, depending on the nature of the changes.
	94	+* Changes during the Create phase typically involve modifications to gateway messages, with changes reflected automatically in the Swagger definition and a version bump of the infra flow.
	95	+* Adding new operations or updating from either Design or Create does not require a reset of the existing solution.
	96	+* Ensure that updates are included in the deployment phase to reflect the latest changes in the Swagger file and runtime infra flow.
97	97
98		-As this is a more theoretical microlearning we did not provide a video for this one.
	98	+== 5. Suggested Additional Readings ==
99	99
	100	+If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following link:
	101	+
	102	+* [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]
	103	+** [[Crash Course API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]
	104	+*** [[Swagger UI (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-swagger-ui||target="blank"]]
	105	+*** [[Parameters (Path, Query) (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-parameters||target="blank"]]
	106	+*** [[Configure A Backend Operation (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-configure-backend-operation||target="blank"]]
	107	+*** [[Setting up Entry gate (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-setting-up-entry-gate||target="blank"]]
	108	+*** [[Setting up Exit gate (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-setting-up-exit-gate||target="blank"]]
	109	+*** [[API Gateway Security (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-security||target="blank"]]
	110	+* [[Updating API Gateway Operations (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=updating+%22API+gateway%22+operation||target="blank"]]
100	100	)))((({{toc/}}))){{/container}}{{/container}}