Defining Web Service Parameters

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Calling Web Services > Adding a Web Service Call (REST-Style) >

Defining Web Service Parameters

When you need to call a Web service with URL parameters, the parameters must be explicitly defined on the Web Service Call Settings dialog box. This dialog box also lets you configure the Web service request with custom headers.

 

 

To define Web service parameters:

1.Double-click the title bar of the Web service component on the mapping, or right-click it and select Properties. The Web Service Call Settings dialog box opens.

mf_ws_03

2.Under Service Definition, select Manual. As illustrated above, you can enter the parameters manually, or, as an alternative, you can import them from an existing URL or from a WADL file. The imported parameters become available in the Parameters table, where you can further modify them if required.
3.Use the Add Parameter ( ic_paramadd ) and Delete Parameter ( ic_paramdel ) buttons, respectively.

 

The columns in the Parameters table have the following meaning:

 

Name

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.

Style

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 https://www.iana.org/assignments/message-headers/message-headers.xhtml.

 

Use the "Query" style for URL parameters that define key-value pairs using the format: ?key=value&key=value

 

For example: http://example.org/api/products?sort=asc&category=1&page=1

 

Use the "Template" style for URL parameters enclosed within curly brackets, for example: http://example.org/api/products/{id} . For such parameters, MapForce escapes the values according to the RFC 6570 rules (https://tools.ietf.org/html/rfc6570).

 

Use the "Matrix" style for URL parameters that define key-value pairs in the format: ;key=value;key=value;

 

For example: 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" (see also next option).

Type

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. Nevertheless, 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.

Mappable

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.

Fixed Value

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

Required

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 (that is, an error message is displayed if the parameter does not have a value).

Repeating

Specifies whether the parameter is single-valued or may have multiple values. This setting is applicable only for mappable parameters. It 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 on the mapping, instead of a single value. MapForce will then handle the sequence of values depending on the style of the parameter, as follows:

 

For "Template" parameters, the values will be supplied to the Web service as comma-separated, for example: http://example.org/api/products/1,2,3
For "Query" parameters, the parameter name will be repeated for each value, for example: http://example.org/api/products?color=red&color=green&color=blue
If the style is "Matrix", multiple values will be separated by comma, for example: 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.

Description

Specifies the optional description of the parameter. If the parameter is mappable, the description entered here appears on 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.

mf_ws_03

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

mf_ws_04

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 "Template".

 

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 "Template".

 

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.

mf_ws_05


© 2019 Altova GmbH