Skip to Content

Wiki source code of API Data model

Last modified by Martijn Woudstra on 2022/08/11 10:43
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on learning about the API Data model.
3 As with every integration pattern eMagiz gives you the option to create your data model.
4 This data model can be based on standards (i.e. OTM5), can be custom made, or a combination of both.
5
6 For API the data model represents the structure of messages that you want to publish to the outside (other parties or other internal systems) world.
7
8 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
9
10 == 1. Prerequisites ==
11
12 * Basic knowledge of the eMagiz platform
13
14 == 2. Key concepts ==
15
16 This microlearning centers around the API Data Model.
17 With API we mean: A collection of definitions based on which a client can communicate with applications
18 With a data model we mean: A collection of elements (entities and attributes) that represent how you view those elements and how you want to converse about those elements
19
20 The data model consists of the following:
21
22 * Entities with their characteristics
23 * Relationships between entities
24
25 And has as a goal to create a landscape-wide overview of the collection of elements that are integrated via the eMagiz platform.
26
27 == 3. API Data Model ==
28
29 As with every integration, pattern eMagiz gives you the option to create your data model.
30 This data model can be based on standards (i.e. OTM5), can be custom made, or a combination of both.
31
32 For API the data model represents the structure of messages that you want to publish to the outside (other parties or other internal systems) world.
33
34 You can access the API data model in the Design phase of eMagiz. To do so you have to navigate to Design and open the context menu on the API block in the center of your Design Overview
35
36 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--access-data-model-in-design.png]]
37
38 When you select this option eMagiz will take you to the Gateway (API) Data Model.
39 When you enter this overview for the first time you will see an empty canvas.
40
41 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--data-model-in-design-empty.png]]
42
43 On this canvas, you can either drag and drop items (just as we discussed in our Crash Course Platform * Creating a Message Definition)
44 or you can opt to Import from an XSD file. In either case, you need to enter "Start Editing" mode first.
45
46 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--import-data-model-in-design.png]]
47
48 You can also import part of the data model and extend it further with the help of manual editing or importing a second part of the data model later on as the model grows.
49
50 So for example your data model could look like this after you have imported two separate XSD files into the API Gateway Data Model
51
52 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--import-data-model-in-design-filled-in.png]]
53
54 === 3.1 Saving your changes ===
55
56 After you are done with editing on this data model you can press "Stop Editing" and you will be presented with the following pop-up
57
58 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--create-new-version-pop-up.png]]
59
60 At this point, you have to make a choice. If you are satisfied with your work you press Save and create a new version.
61 If you are unsure of your work or simply need to stop because there is no more time left go for the option Save and continue.
62
63 ==== 3.1.1 Save and create new version ====
64
65 When you go for the option Save and create a new version you will see the following pop-up
66
67 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--save-and-create-new-version-pop-up.png]]
68
69 Choose whether this was a major, minor, or patch upgrade and give a description of the version that tells you and others what you have changed. Something like this
70
71 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--save-and-create-new-version-pop-up-filled-in.png]]
72
73 Press the button Create version and eMagiz will save your changes.
74
75 ==== 3.1.2 Save and continue ====
76
77 When you are not sure that the version you are currently working on is ready for Deploy you can select the other option called Save and continue.
78 When choosing this option eMagiz will automatically create a temporary version of your flow in its current state.
79 You can view who made what (temporary) version when you navigate to the History option on the API Gateway Data Model level.
80
81 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--history-of-data-model.png]]
82
83 This history of the changes on the API Gateway Data Model is not only useful for auditing purposes but also helps you identify who you should ask about the latest changes.
84 As you can see the default description of an autosaved version is Autosaved version. You can give such a version a more descriptive name by selecting it and pressing Edit.
85
86 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--edit-description-auto-saved-version.png]]
87
88 That action will lead you to the following pop-up. In this pop-up, you can change the description of the autosaved version to something that makes clear what you did.
89
90 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--edit-description-auto-saved-version-pop-up.png]]
91
92 Simply press Save when you are done and the description will be changed
93
94 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-data-model--edit-description-auto-saved-version-result.png]]
95
96 == 4. Assignment ==
97
98 Import two definitions (XSD's) into your API Gateway Data Model and change one of the attributes to indicate that it is confidential
99 This assignment can be completed with the help of an associated Mendix project linked to the (Academy) project that you have created/used in the previous assignment.
100
101 == 5. Key takeaways ==
102
103 * The API data model can be based on standards (i.e. OTM5), can be custom made, or a combination of both.
104 * The data model consists of the following:
105 * Entities with their characteristics
106 * Relationships between entities
107 * Multiple ways of creating and editing the data model
108 * You can import from outside sources
109 * You can build it from scratch
110 * You can use any combination of the above-mentioned options in any order
111 * Changes on API Gateway Data Model are kept in History and it is up to the user to make it clear what has changed
112
113
114 == 6. Suggested Additional Readings ==
115
116 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
117
118 == 7. Silent demonstration video ==
119
120 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!
121
122 {{video attachment="crashcourse-api-gateway-api-data-model.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
123
124 )))((({{toc/}}))){{/container}}{{/container}}