Skip to Content
Last modified by Danniar Firdausy on 2024/09/18 13:34
From version 2.2
edited by Bouke Reitsma
on 2023/02/28 16:32
Change comment: There is no comment for this version
To version 14.1
edited by Eva Torken
on 2023/08/23 13:30
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Changing the default messaging format to XML
1 +Changing the default messaging format
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.BoukeReitsma
1 +XWiki.etorken
Content
... ... @@ -1,6 +1,6 @@
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. By default, the messaging format chosen for your gateway is json. However, in some instances XML is more appropriate as default message format. In this microlearning, we focus on changing the default message format and show the impact this has on flows in Create.
3 +In our crash course on the API Gateway pattern, we have learned about setting up the API Gateway. By default, the messaging format chosen for your gateway is JSON. However, in some instances, other message formats are more appropriate as default. In this microlearning, we focus on changing the default message format and show the impact this has on flows in Create.
4 4  
5 5  Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
6 6  
... ... @@ -10,86 +10,32 @@
10 10  
11 11  == 2. Key concepts ==
12 12  
13 -This microlearning centers around updating your API Gateway.
13 +There are no specific concepts to consider for now that require additional explanation.
14 14  
15 -By updating, we mean: Changing existing software to reflect new insights or ideas that have come up during development and/or testing
15 +== 3. Changing the default messaging format ==
16 16  
17 -* Updating can happen from Design
18 -* Updating can happen from Create
19 -* Both situations have a different impact
17 +In our crash course on the API Gateway pattern, we have learned about setting up the API Gateway. By default, the messaging format selected for your gateway is JSON. However, the default messaging format can be changed in your project to for example, XML. This change can be made in Design -> Settings -> API Management. On the right side of this overview are the gateway settings. The last entry of this overview is the Default Format. By clicking on the Edit settings button, you enter the following overview
20 20  
21 -== 3. Updating your API Gateway Operations ==
22 -
23 - {{info}}~* Note GIVE INFO{{/info}}
19 +[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-changing-default-messaging-format--edit-settings.png]]
24 24  
25 -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.
21 +The last option allows you to switch between JSON or XML as your default messaging format in the gateway. In order to apply your new default to your project, you must press "Apply settings" in Design -> Architecture to confirm your change~*.
26 26  
27 -* Updating can happen from Design
28 -* Updating can happen from Create
29 -* Both situations have a different impact
23 +{{info}}~* Note Changing the default messaging format does not affect existing operations in Create. Migrating these flows requires a reset of the exit flow. Additionally, the default response in Catalog has to be changed to application/xml. {{/info}}
30 30  
31 -In the remainder of this microlearning, we will discuss both scenarios. This to get clarity on what the impact is of both scenarios.
25 +== 4. Impact in Create ==
32 32  
33 -=== 3.1 Updating from Design ===
27 +After the flows are resetted in Create, the automatic flow creation in the Create phase is adapted to the new default setting. When changing the messaging format to XML, the components of newly generated flows are created with different names and settings. The image below shows an example of an API GET operation with XML as the default messaging format. Besides the changed naming of the transformation, no JSON factory support objects are required in your flow in comparison with a JSON messaging format.
34 34  
35 -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.
29 +[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-changing-default-messaging-format--get-operation.png]]
36 36  
37 -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:
31 +== 4. Key takeaways ==
38 38  
39 -* 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
40 -* 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
41 -* When you change the gateway request/response message (with transformation) the change will impact **both** the all-entry and the specific exit gate
33 +* The default messaging format can be changed to XML
34 +* Updating this only affects new flows
35 +* Migrating existing operations can be done by resetting the exit flow
42 42  
43 -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.
37 +== 5. Suggested Additional Readings ==
44 44  
45 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--reset-flow-context-menu.png]]
39 +If you are interested in this topic and want more information on it, please read the help text provided by eMagiz.
46 46  
47 -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.
48 -
49 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--reset-flow-warning.png]]
50 -
51 -After you reset your all-entry eMagiz will update the following:
52 -
53 -* Swagger UI that is shown to clients via the Swagger documentation page
54 -* Parameter references
55 -* Error Handling
56 -* Many more
57 -
58 -This all depends on which changes you **made** on the Design level.
59 -
60 -=== 3.2 Updating from Create ===
61 -
62 -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:
63 -
64 -* Changing the dataType (i.e. from dateTime to date)
65 -* Adding valid enum values
66 -
67 -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 -
69 -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 -
71 -== 4. Assignment ==
72 -
73 -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.
74 -This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
75 -
76 -== 5. Key takeaways ==
77 -
78 -* Updating can happen from Design
79 -* Updating can happen from Create
80 -* Both situations have a different impact
81 -* Adding a new operation to an existing solution does not involve a reset
82 -* Updating from Create does not involve a reset
83 -* Updating from Design involves a reset
84 -
85 -
86 -
87 -== 6. Suggested Additional Readings ==
88 -
89 -If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
90 -
91 -== 7. Silent demonstration video ==
92 -
93 -As this is a more theoretical microlearning we did not provide a video for this one.
94 -
95 95  )))((({{toc/}}))){{/container}}{{/container}}