Wiki source code of Parameters (Path, Query)

Last modified by Eva Torken on 2023/06/08 11:35
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on learning about parameters that can be part of the resource path.
3 In the previous couple of microlearnings, we learned how to build up the resource path and how to select the correct HTTP method.
4
5 In this microlearning, we will expand on this by talking about parameters.
6
7 For API a parameter represents a dynamic part or extension of the resource path
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 parameters (Path, Query).
16 With API we mean: A collection of definitions based on which a client can communicate with applications
17 With parameters we mean: A dynamic part or extension of the resource path
18
19 There are two main parameters when working with APIs:
20 * Path
21 ** Part of the path
22 ** Mandatory
23 * Query
24 ** Extension of the resource path
25 ** Optional (mostly)
26
27 == 3. Parameters (Path, Query) ==
28
29 Building on what we learned in the previous microlearnings we now take a look at the dynamic parts of API endpoints.
30
31 There are two main parameters when working with APIs:
32 * Path
33 ** Part of the path
34 ** Mandatory
35 * Query
36 ** Extension of the resource path
37 ** Optional (mostly)
38
39 Below we will discuss both of them and tell you how you should configure them in eMagiz
40
41 === 3.1 Path ===
42
43 Let's start with Path parameters. Path parameters are mandatory parts of the resource path that can be filled in dynamically.
44 A classic example of using a path parameter is when you execute a GET call to retrieve one specific resource (i.e. Order, Client, Invoice).
45 The full path, including path parameter, would then look as follows:
46
47 * {{code}}/orders/{uuid}{{/code}}
48
49 The notation of a Path parameter is the name of the path parameter encapsulated with curly brackets. In this case, the path parameter label is UUID.
50 When an external client would call this endpoint they will replace the parameter placeholder with a valid UUID for which they want to retrieve the order information.
51 An example would be:
52
53 * {{code}}/orders/12345{{/code}}
54
55 If an order with that specific UUID exists in our backend we will return the information to the client.
56 In case a client does not send this value they will be faced with a 404 not found error because you have to fill in a path parameter as it is mandatory
57
58 === 3.2 Query ===
59
60 The second parameter that is used frequently is the query parameter. Query parameters are mostly optional and can help you to filter or sort a collection of resources.
61 So let us say that apart from making it possible for our external clients to retrieve a single order (via the path parameter option)
62 we could also make it possible to limit the result set based on a characteristic, for example, customer via a GET call.
63
64 The correct notation of the resource path would then be as follows:
65
66 * {{code}}/orders?customer=eMagiz{{/code}}
67
68 This call will return all orders for which the characteristic (customer) is equal to eMagiz.
69 By making this optional you can re-use the same endpoint to retrieve all orders and to filter on certain characteristics if there is a need.
70
71 So to summarize the difference between path and query parameters:
72
73 * Path parameters are always mandatory whereas query parameters are mostly optional
74 * Path parameters narrow the scope down to a single iteration whereas query parameters offer you the option to filter a result set
75
76 === 3.3 Configure parameters ===
77
78 ==== 3.3.1 Expose from backend operation ====
79
80 Now that we know what the main differences are let us take a look at how you can implement them in eMagiz.
81 As you know from our previous microlearning on HTTP Operations you can expose backend operations.
82 Once again if they have a solid base re-use that, eMagiz will include path and query parameters if they exist in the backend operation.
83
84 ==== 3.3.2 Add/Edit Path Parameters ====
85 When that is not the case however you can add and edit the path parameters to your API Gateway Catalog in the following way.
86 The first step is to open the API Gateway Catalog.
87 This can be done through a right-click on the API component in the center of your Design overview to select the option Edit Catalog.
88
89 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--access-api-catalog-in-design.png]]
90
91 Here you see an overview of all resource paths, operations, and also parameters
92
93 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design.png]]
94
95 In case you want to add a path parameter you need to first change the resource path to identify which part of the resource path is based on the dynamic entry of a parameter value.
96 In this case, we want to limit the scope of what people can retrieve when calling the HTTP methods endpoint to one specific HTTP method.
97
98 To do so we select the resource path and press Edit
99
100 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-edit-resource-path.png]]
101
102 In the pop-up that follows you will be able to edit the resource path accordingly. This change should result in something like this. When you are happy you can press Save.
103
104 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-edit-resource-path-result.png]]
105
106 The second step would be to add this parameter and link it to this resource path. You can do that on the same screen. On the right side of the screen, you have the parameters tab
107
108 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameters.png]]
109
110 By pressing the button new you can add your parameter with the help of the following pop-up.
111
112 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config.png]]
113
114 The crucial element in this pop-up is the name of the parameter. That should match with the name of the parameter you have changed in the resource path itself. In this example that would be: method
115
116 The rest is correct by default. For illustrative purposes, it would be good to add an example of a value that is expected. Save when ready
117
118 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config-result.png]]
119
120 If you want to change something simply select the parameter and press Edit to edit the parameter
121
122 ==== 3.3.2 Add/Edit Query Parameters ====
123 When that is not the case however you can add and edit the query parameters to your API Gateway Catalog in the following way
124 The first step is to open the API Gateway Catalog.
125 This can be done through a right-click on the API component in the center of your Design overview to select the option Edit Catalog.
126
127 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--access-api-catalog-in-design.png]]
128
129 Here you see an overview of all resource paths, operations, and also parameters
130
131 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design.png]]
132
133 In the case of a path parameter, we needed to specify where in the path it would end up.
134 For query parameters, we don't need to do so because they are always an extension of the resource path at the **end** of a resource path.
135
136 On the right side of the screen, you have the parameters tab
137
138 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameters.png]]
139
140 By pressing the button new you can add your parameter with the help of the following pop-up.
141
142 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config.png]]
143
144 To add a query parameter you give the parameter a name here and you select the option Query instead of Path. An example of this filled-in looks as follows.
145
146 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config-result-query.png]]
147
148 If you want to change something simply select the parameter and press Edit to edit the parameter
149
150 == 4. Key takeaways ==
151
152 There are two main parameters when working with APIs:
153 * Path
154 ** Part of the path
155 ** Mandatory
156 * Query
157 ** Extension of the resource path
158 ** Optional (mostly)
159
160 To summarize the difference between path and query parameters:
161
162 * Path parameters are always mandatory whereas query parameters are mostly optional
163 * Path parameters narrow the scope down to a single iteration whereas query parameters offer you the option to filter a result set
164
165 == 5. Suggested Additional Readings ==
166
167 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
168
169 )))((({{toc/}}))){{/container}}{{/container}}