Parameters (Path, Query)

{{container}}{{container layoutStyle="columns"}}(((

In this microlearning, we will delve into the concept of parameters within the resource path of an API. Building on our previous discussions about constructing resource paths and selecting appropriate HTTP methods, we will now explore how parameters can dynamically extend or specify parts of these paths. By the end of this session, you'll understand the distinction between path and query parameters and how to effectively configure them within the eMagiz platform.

3

4

If you have any questions along the way, feel free to reach out to us at [[academy@emagiz.com>>mailto:academy@emagiz.com]].

5

6

== 1. Prerequisites ==

7

* Basic knowledge of the eMagiz platform

8

9

== 2. Key concepts ==

10

This microlearning centers around parameters (Path, Query).

11

12

* With API we mean: A collection of definitions based on which a client can communicate with applications

13

* With parameters we mean: A dynamic part or extension of the resource path

14

15

== 3. Parameters (Path, Query) ==

16

17

Building on what we learned in the previous microlearnings we now take a look at the dynamic parts of API endpoints.

18

19

There are two main parameters when working with APIs:

* Path

** Part of the path

** Mandatory

* Query

** Extension of the resource path

25

** Optional (mostly)

26

27

Below we will discuss both of them and tell you how you should configure them in eMagiz

=== 3.1 Path ===

Let's start with Path parameters. Path parameters are mandatory parts of the resource path that can be filled in dynamically.

32

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).

33

The full path, including path parameter, would then look as follows:

34

35

* {{code language=text}}/orders/{uuid}{{/code}}

36

37

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.

38

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.

39

An example would be:

40

41

* {{code language=text}}/orders/12345{{/code}}

42

43

If an order with that specific UUID exists in our backend we will return the information to the client.

44

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

=== 3.2 Query ===

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.

49

So let us say that apart from making it possible for our external clients to retrieve a single order (via the path parameter option)

50

we could also make it possible to limit the result set based on a characteristic, for example, customer via a GET call.

51

52

The correct notation of the resource path would then be as follows:

53

54

* {{code language=text}}/orders?customer=eMagiz{{/code}}

55

56

This call will return all orders for which the characteristic (customer) is equal to eMagiz.

57

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.

58

59

So to summarize the difference between path and query parameters:

60

61

* Path parameters are always mandatory whereas query parameters are mostly optional

62

* Path parameters narrow the scope down to a single iteration whereas query parameters offer you the option to filter a result set

63

64

=== 3.3 Configure parameters ===

65

66

==== 3.3.1 Expose from backend operation ====

67

68

Now that we know what the main differences are let us take a look at how you can implement them in eMagiz.

69

As you know from our previous microlearning on HTTP Operations you can expose backend operations.

70

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.

71

72

==== 3.3.2 Add/Edit Path Parameters ====

73

When that is not the case however you can add and edit the path parameters to your API Gateway Catalog in the following way.

74

The first step is to open the API Gateway Catalog.

75

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.

76

77

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--access-api-catalog-in-design.png]]

78

79

Here you see an overview of all resource paths, operations, and also parameters

80

81

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design.png]]

82

83

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.

84

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.

85

86

To do so we select the resource path and press Edit

87

88

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-edit-resource-path.png]]

89

90

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.

91

92

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-edit-resource-path-result.png]]

93

94

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

95

96

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameters.png]]

97

98

By pressing the button new you can add your parameter with the help of the following pop-up.

99

100

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config.png]]

101

102

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

103

104

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

105

106

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config-result.png]]

107

108

If you want to change something simply select the parameter and press Edit to edit the parameter

109

110

==== 3.3.2 Add/Edit Query Parameters ====

111

When that is not the case however you can add and edit the query parameters to your API Gateway Catalog in the following way

112

The first step is to open the API Gateway Catalog.

113

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.

114

115

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--access-api-catalog-in-design.png]]

116

117

Here you see an overview of all resource paths, operations, and also parameters

118

119

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design.png]]

120

121

In the case of a path parameter, we needed to specify where in the path it would end up.

122

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.

123

124

On the right side of the screen, you have the parameters tab

125

126

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameters.png]]

127

128

By pressing the button new you can add your parameter with the help of the following pop-up.

129

130

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config.png]]

131

132

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.

133

134

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-api-gateway-parameters--api-catalog-in-design-parameter-config-result-query.png]]

135

136

If you want to change something simply select the parameter and press Edit to edit the parameter

137

138

== 4. Key takeaways ==

139

140

There are two main parameters when working with APIs:

* Path

** Part of the path

** Mandatory

* Query

** Extension of the resource path

146

** Optional (mostly)

147

148

To summarize the difference between path and query parameters:

149

150

* Path parameters are always mandatory whereas query parameters are mostly optional

151

* Path parameters narrow the scope down to a single iteration whereas query parameters offer you the option to filter a result set

152

153

== 5. Suggested Additional Readings ==

154

155

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 links:

156

157

* [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]

158

** [[Crash Course API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]

159

*** [[HTTP Resources (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-resource-paths||target="blank"]]

160

*** [[Swagger UI (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-swagger-ui||target="blank"]]

161

*** [[Configure A Backend Operation (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-configure-backend-operation||target="blank"]]

162

* [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]

163

** [[REST Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.WebHome||target="blank"]]

164

*** [[Configuration REST web service (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.intermediate-rest-webservice-connectivity-configuration-gen3.WebHome||target="blank"]]

165

*** [[HTTP Headers (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.intermediate-rest-webservice-connectivity-http-headers||target="blank"]]

166

** [[API Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.WebHome||target="blank"]]

167

*** [[Updating your API Gateway Operations (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.intermediate-api-management-updating-your-api-gateway-operations||target="blank"]]

168

* [[Parameters (Path, Query) (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=Parameters%20%28Path%2C%20Query%29||target="blank"]]

169

)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Parameters (Path, Query)

Navigation