FME Transformers: 2024.1
FME Transformers: 2024.1
OpenAPICaller
Accesses an API endpoint defined by an OpenAPI specification via HTTP or HTTPS.
Import from OpenAPI Specification
This transformer must be configured by importing an OpenAPI specification JSON or YAML file. To do this:
- Download the specification file
- Use the Select button to access the import dialog
- Provide the file location in the Specification parameter
- Select from the available endpoints, and the OpenAPICaller dialog will be populated as specified, including Full Request URL, Authentication Method, and request details such as Query String Parameters and Headers.
Note that any selections made here will overwrite current parameter values.
Examples
Example: Importing from an OpenAPI specification and testing the query
In this example, we will configure an OpenAPICaller to retrieve a list of available emojis from Trello via their OpenAPI specification.
Note that the specification file must be downloaded before using it here - they cannot be read via a URL. It will be either a JSON or YAML file.
In the parameters dialog, use the Select button to access the import dialog.
In the import dialog, navigate to the previously-downloaded specification file.
One the specification file is selected, available Endpoint options are populated.
We select the emoji endpoint, and its GET method. Note the applicable Query Parameters are also retrieved.
Import Request Parameters will apply the selections to the appropriate OpenAPICaller parameters.
The applicable parameters have been configured.
To test the configuration, we use the Send Test Request button.
In the test request dialog, a preview of the query is shown.
Note that if there were any user parameters in the query, they would be available and editable for testing.
Send Test Request will execute the query.
The query test results are returned in Test Response Preview.
These results (and any configuration changes made to user parameters, if present) are saved for future reference but will not affect the transformer's actual parameter settings.
Configuration
Input Ports
Input
This transformer accepts any feature.
Output Ports
Output
The HTTP response body may be saved to an attribute, or a file. By default the body is saved to the attribute identified by the Response Body Attribute parameter.
The HTTP response status code will be stored in the attribute named by the Status Code Attribute parameter. By default this is the _http_status_code attribute. For more information on HTTP Status Codes, please refer to https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
In addition, the HTTP response headers will be saved in the list attribute specified by the Multipart Header List Attribute parameter. By default the headers are stored in the _headers{} list attribute. For a list of common HTTP response headers, please refer to https://en.wikipedia.org/wiki/List_of_HTTP_header_fields.
<Rejected>
If an error occurs while accessing the URL, the feature will be output via the <Rejected> port. In addition, an error message will be set in the attribute named by the Error Attribute parameter.
Rejected Feature Handling: can be set to either terminate the translation or continue running when it encounters a rejected feature. This setting is available both as a default FME option and as a workspace parameter.
Parameters
Request
Authentication |
If enabled, provide authentication details as needed.
|
||||||||||||||||
URL by Parameters |
This group divides up the Full Request URL into several components which can be edited separately. Any changes made to these parameters will be reflected in the value of the Full Request URL parameter.
|
||||||||||||||||
Full Request URL |
This parameter identifies the URL which will be accessed by the transformer. The URL can be edited directly in this parameter, or by editing the parameters in the URL by Parameters group above. Any changes made to this parameter will be reflected in the URL by Parameters group. |
||||||||||||||||
Headers |
This table can be used to create custom HTTP headers which will be sent along with the request. This can be used to customize the request that FME will make to the server. Header names and values can be entered directly or constructed from attribute values. In addition, the Name column provides a list of commonly used header names. |
||||||||||||||||
Body |
These parameters are only enabled when HTTP Method is PUT, POST, DELETE, or PATCH. An upload body is not required; for example, DELETE requests often have no upload body.
|
Output Configuration
Response Handling Mode |
This parameter allows users to determine how the HTTP response body should be processed. |
||||||||||||||||||||||
Output JSON Fragments as Features |
When Response Handling Mode is Ouput JSON Fragments as Features, this mode performs JSON post processing on the response body, equivalent to inserting JSONFlattener and JSONFragmenter transformers after the OpenAPICaller. The object keys and values contained within the response body will be extracted into FME feature attributes. The response body can optionally be split up into multiple features using the JSON Query to Fragment parameter. If the response body does not contain valid json the feature will be output through the <Rejected> port.
|
||||||||||||||||||||||
Save Entire Response Body |
When Response Handling Mode is Save Entire Response Body, this parameter allows users to set the destination for the HTTP response body.
Note If you are downloading a very large response body with the OpenAPICaller, it is recommended that you save it to a file. This avoids creating a large attribute on the feature.
|
||||||||||||||||||||||
Response Header and Status Attributes |
|
||||||||||||||||||||||
Multipart Response Handling |
It is rare, but possible for an HTTP server to return a multipart response. That is, a single HTTP request will result in an HTTP response which contains several different parts. A multipart response will have a Content-Type header which begins with "multipart", such as "multipart/mixed". The OpenAPICaller has the Feature Output option to split such responses into multiple features. Because multipart responses are very rare, the default behavior is to not split multipart responses into multiple features. These parameters are only enabled when response bodies are being saved to attributes, or to a folder.
|
Advanced
Concurrent Requests |
|
||||||
Retry Failed Requests |
When enabled, the OpenAPICaller will attempt to retry requests which have failed, or have returned an HTTP error.
|
||||||
Rate Limiting |
|
||||||
HTTP Client Options |
|||||||
Advanced Security |
|
Import from OpenAPI Specification
Specification |
Specify a JSON or YAML OpenAPI specification file to use. This file must be downloaded (URLs are not supported). |
Select Endpoint |
Select an available option to have its details populated in the main parameter dialog. |
Editing Transformer Parameters
Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.
How to Set Parameter Values
Defining Values
There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters.
Using the Text Editor
The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.
Using the Arithmetic Editor
The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.
Conditional Values
Set values depending on one or more test conditions that either pass or fail.
Parameter Condition Definition Dialog
Content
Expressions and strings can include a number of functions, characters, parameters, and more.
When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.
Content Types
These functions manipulate and format strings. | |
Special Characters |
A set of control characters is available in the Text Editor. |
Math functions are available in both editors. | |
Date/Time Functions | Date and time functions are available in the Text Editor. |
These operators are available in the Arithmetic Editor. | |
These return primarily feature-specific values. | |
FME and workspace-specific parameters may be used. | |
Creating and Modifying User Parameters | Create your own editable parameters. |
Dialog Options - Tables
Table Tools
Transformers with table-style parameters have additional tools for populating and manipulating values.
Row Reordering
|
Enabled once you have clicked on a row item. Choices include:
|
Cut, Copy, and Paste
|
Enabled once you have clicked on a row item. Choices include:
Cut, copy, and paste may be used within a transformer, or between transformers. |
Filter
|
Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output. |
Import
|
Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers. |
Reset/Refresh
|
Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers. |
Note: Not all tools are available in all transformers.
For more information, see Transformer Parameter Menu Options.
Reference
Processing Behavior |
|
Feature Holding |
No |
Dependencies | None |
Aliases | |
History | This transformer replaces Import from OpenAPI feature in the HTTPCaller. |
FME Community
The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.
Search for all results about the OpenAPICaller on the FME Community.
Examples may contain information licensed under the Open Government Licence – Vancouver, Open Government Licence - British Columbia, and/or Open Government Licence – Canada.