OpenAPI
The OpenAPI Specification is used to define HTTP APIs. It describes the endpoints, operations, input and output parameters, security parameters and other details of an API, usually in JSON or YAML format. MapForce supports the OpenAPI Specification 2.0 (formerly know as Swagger RESTful API Documentation Specification), 3.0, and 3.1.
The OpenAPI settings you can configure are shown in the screenshot below. For more information about each setting, see the subsections below.
OpenAPI settings
To fill in the parameters of a Web service call, you will need to supply an OpenAPI file that describes the Web service: Click Browse next to the OpenAPI File field and select the relevant file. As soon as you select the OpenAPI file, the settings of this Web service will be filled in automatically. If necessary, you can change any of the settings. This will not affect the OpenAPI file.
OpenAPI file | This is the path to the OpenAPI Specification file that describes the Web service.
|
Path and Operation | The Path field refers to an API's endpoint (e.g., /users) that MapForce needs to call the desired function. All paths are relative to the API server URL (see below).
Operations refer to HTTP methods (e.g., GET, DELETE, POST) that are used to perform different actions on paths. Select a path and then one operation for that path (e.g., POST /users to add a new user). There can be multiple paths available, and for each path, there can be one or more operations defined.
The path and operation are configurable via the same Choose button. When you click this button, a dialog (screenshot below) will pop up and prompt you to select a path and an operation for it. In the screenshot below, the POST operation has been selected for the /pets path.
|
Server | The Server field refers to an API's base URL (e.g., https://api.example.com) to which endpoint paths are relative (e.g., https://api.example.com/users).
|
By default, the selected Server and Path fields are concatenated to make up the URL in the Connection Settings (see below).
Connection settings
URL | The URL text box specifies the address (URL) of the Web service you want to call.
| ||
Dynamic URL (supplied by mapping) | If you would like to supply the URL of the Web service from the mapping, select the Dynamic URL (supplied by mapping) check box. This creates an additional input connector in the Web service component in the mapping, to which you can connect some input which provides the URL of the Web service.
With fully or partially dynamic URLs, you can flexibly adjust the URL according to your needs. For example, you could run the mapping with a specific URL during development and use a different URL in production, without modifying the mapping. A URL like https://{host}/some/path/to/service would make this possible, assuming that the host name is the only difference between the production and testing URLs, and you supply it as a parameter to the mapping. Note that partially dynamic URLs enforce stricter validation, since only the designated URL parts are replaced with mappable or runtime values.
With fully dynamic URLs, the entire URL is mappable and you have complete control over it; the only requirement is that the URL must begin with http:// or https:// and it must be a valid URL. Dynamic URLs also make it possible to supply the URL returned from a Web service call as input to another component which may call the same (or some other) Web service.
| ||
Timeout | The Timeout parameter defines the time interval after which the Web service call will time out if there is no response from the server. Select Infinite if the call should wait for a response for an indefinite amount of time.
|
Notes about parameters in URL
You can optionally turn specific parts of the URL into parameters and supply values to these parameters from the main mapping. For URLs defined this way, note the following:
•If you call a Web service with template- or matrix-style parameters, enclose the parameters within curly braces, for example: http://example.org/api/products/{id}. Then define the settings of each parameter in the Parameters table. At runtime, MapForce replaces the placeholders in curly braces with the actual parameter values and produces the final URL.
•If you call a Web service with query URL parameters (e.g., http://example.org/api/products?sort=asc&category=1&page=1), do not enter the query part in the URL text box. Instead, define the parameters only in the Parameters table and make sure to designate them as query-style parameters.
Parameters
The parameters defined in the OpenAPI file are displayed in the Parameters section of the Web Service Call Settings dialog (screenshot below). For each parameter, you need to define if the parameter is mappable or has a fixed value, but you should not modify any other settings of the OpenAPI-defined parameters unless they are incorrect.
If the OpenAPI file has been updated, and the service has received additional or different parameters, click the Reset button to update the parameters.
As for adding new parameters, you will usually need to add only missing, undocumented parameters in the Parameters section.
For details about the settings you can configure in the Parameters section, see Parameters.
HTTP security settings
You may need to configure HTTP security settings in the following scenarios:
•The Web service is called through HTTPS and requires a client certificate.
•The server uses an incorrect certificate, and you would like to allow a host name mismatch between the certificate and request.
•The Web service requires basic HTTP authentication or OAuth 2.0 authorization.
For more information, see HTTP Security Settings.
Save all file paths relative to MFD file
When this option is enabled, MapForce saves the file paths displayed in the Component Settings dialog box relative to the location of the MapForce Design (.mfd) file. See also Relative and Absolute Paths.