REST Web Service Parameters
When you need to call a Web service with URL parameters, the parameters must be defined in the Web Service Call Settings dialog box. This dialog box also lets you configure the Web service request with custom headers. You can configure the parameter values to be mappable (supplied by the mapping) or fixed (defined on the dialog box).
To define Web service parameters, take the following steps:
1.Double-click the title bar of the Web service component in the mapping or right-click it and select Properties. The Web Service Call Settings dialog box opens.
2.Under Service Definition, select Manual. You can enter the parameters manually or automatically (by importing them from an existing URL or from a WADL file). The imported parameters become available in the Parameters table (see subsection below), where you can further modify them if required.
3.Use the Add Parameter ( 
) and Delete Parameter ( 
) buttons, as required.
Parameters
The subsections below summarize the available parameters in the Web Service Call Settings dialog.
Specifies the name of the URL parameter. The parameter name must be unique and may consist of letters, digits, periods (.), hyphens (-) and underscores (_). No spaces are allowed in the parameter name.
|
Specifies the syntax (style) of the URL parameter.
•Use the Header style to add a parameter to the HTTP header when calling the Web service. For example, adding a parameter Accept with value text/xml is equivalent to specifying the Accept: text/xml header, which informs the Web server that MapForce expects the response to be in XML format. For more information about HTTP headers, see the Message Headers Specification. •Use the Query style for URL parameters that define key-value pairs using the ?key=value&key=value format (e.g., http://example.org/api/products?sort=asc&category=1&page=1) •Use the Template style for URL parameters enclosed within curly braces (e.g., http://example.org/api/products/{id}). For such parameters, MapForce escapes the values according to the https://tools.ietf.org/html/rfc6570 RFC 6570 rules. •Use the Matrix style for URL parameters that define key-value pairs in the ;key=value;key=value; format (e.g., http://example.org/api/products;sort=asc;category=1;page=1;). To use Boolean matrix parameters, set the style to Matrix and the type to boolean. •Select Body to send an application/x-www-form-urlencoded request structure to a REST service (the request method must be POST). To find out more about the application/x-www-form-urlencoded format, see the URL Specification.
|
Specifies the data type of the parameter (string, integer, date, etc). This can be any XML Schema type. Note that any value that is not a string is converted to a string when the Web service call takes place. Setting a type is meaningful if you want MapForce to show conversion error messages when you attempt to call a Web service with wrong values.
|
Select this check box if you want to pass values to this parameter from the mapping. This option is mutually exclusive with the Fixed Value option.
|
Specifies the value of the parameter. Applicable only if the parameter has a constant value. Not applicable if the parameter is mappable (see previous option).
|
Select this check box if the parameter is required by the Web service. For parameters that are required and also mappable, MapForce enforces validation checks: An error message is displayed if the parameter does not have a value.
|
Specifies whether the parameter is single-valued or may have multiple values. This setting is applicable only for mappable parameters. This option enables you to pass multiple values in the same Web service call by means of a single parameter. When you select the check box, you can connect a sequence of values to the parameter structure node in the mapping. MapForce will then handle the sequence of values depending on the style of the parameter:
•For Template parameters, the values will be supplied to the Web service as comma-separated (e.g., http://example.org/api/products/1,2,3). •For Query parameters, the parameter name will be repeated for each value (e.g., http://example.org/api/products?color=red&color=green&color=blue). •If the style is Matrix, multiple values will be separated by comma (e.g., http://example.org/api/products;color=red;color=green;color=blue;size=big;size=small;). •If the style is Header, the HTTP header will be repeated for each value.
|
Specifies the optional description of the parameter. If the parameter is mappable, the description entered here appears in the mapping component as an annotation next to the mapping item.
|
Example 1: Header and template parameters
The Web service illustrated below retrieves a product by its identifier (id) using the HTTP GET method. The URL of the Web service specifies the id parameter in the curly brackets. Notice that the id parameter exists in the Parameters table and has the style Template. It is also mappable: this causes the parameter to appear on the mapping as a structure node to which you can connect the actual value of id (which could be, for example, taken from a database, a file, or a constant). At mapping execution runtime, this parameter would be replaced with the actual value; so, if the value is "1", the URL becomes http://example.org/api/products/1 .
To supply a constant id value instead of a value from the mapping, clear the check box "Mappable" and enter the value in the "Fixed value" column.
The parameters Accept and Accept-Charset have the Header style. These parameters are used to call the Web service with custom request headers. There are two ways to supply the header value:
•Leave the option Mappable checked and supply the custom header value from the mapping, or
•Clear the option Mappable and enter the value directly in the "Fixed value" column.
Example 2: Matrix parameters
The Web service illustrated below retrieves a list of products that match the color and size supplied as arguments. The style of the parameters is "Matrix", so they are defined both as placeholders inside the URL and in the mapping table. Notice that the parameters are mappable and the "Repeating" option is checked. This means that their value will be read from some sequence of values on the mapping (for example, a list of rows inside a text file, an XML node, or a database column) and supplied to the Web service at runtime. Thus, a URL such as the one below would become http://example.org/api/products/;color=red;color=blue;size=big;size=small, provided that the mapping supplies red and blue as colors, and big and small as size.
If you need the URL to be http://example.org/api/products;color=red,blue;size=big,small, do the following:
1.Enter the URL as http://example.org/api/products;color={color};size={size}
2.In the Parameters table, change the parameter style to Matrix.
If you need the URL to be http://example.org/api/products?color=red,blue&size=big,small, do the following:
1.Enter the URL as http://example.org/api/products?color={color}&size={size}
2.In the Parameters table, change the parameter style to Matrix.
Example 3: Query parameters
The Web service illustrated below also retrieves a list of products that match the color and size supplied as arguments, this time using the style "Query". For this style, it is not necessary to define the parameters as placeholders in the URL, so they are defined only in the "Parameters" table. In this example, let's assume that the parameter values are fixed and must not be supplied from the mapping. To achieve this, the parameter values were entered under "Fixed Values", and the "Mappable" option is unchecked. Thus, at mapping runtime, the URL below would become http://example.org/api/products?color=red&size=big.
