Introduction
Data Virtualization supports endpoint parameters, which let users refine requests and customize responses. These include path parameters, query parameters, and header parameters.
Parameters are first defined when you create the endpoint metadata in FME Flow. Inside the workspace, you then use readers, writers, and transformers to apply those parameters. These handle the filtering, transformation, and routing based on the values sent in the request.
Endpoint Parameters
Data Virtualization supports all standard types of HTTP parameters:
- Path parameters identify a specific resource by changing the URL path (e.g., /users/{userId}).
- Query parameters filter, sort, or control response content by appending values to the URL (e.g., /search?query=keyword).
- Header parameters provide extra details, such as authentication tokens or metadata (e.g., Authorization: Bearer {token}).
Parameters are optional, giving you flexibility to tailor responses while improving performance and usability.
Documentation may change rapidly and not reflect the current build. This article was written with FME 2025.1.2 b25630.
Learning Objectives
After this lesson, you’ll be able to:
- Update an existing endpoint workspace
- Use endpoint parameters in a workflow
- Test and run parameter values with templates
- Validate request data
Step-by-Step Instructions
In this lesson, the EnvironData Coordination Office will enhance the GET /wildfires endpoint by adding query parameters.
This includes configuring the parameters in FME Flow, updating the workspace in FME Workbench, and republishing the changes.
Two query parameters will be added:
- limit – Specifies the maximum number of results returned.
- status – Filters results based on the wildfire status attribute.
These updates make the API more flexible, allowing users to request data that is both targeted and manageable.
Part 1: Update an Endpoint with Query Parameters
In this part, you’ll define the limit and status parameters by updating the GET /wildfires endpoint metadata in FME Flow. This step configures how the API accepts input from users, setting up each parameter’s name, type, and location in the request. Defining parameters here lays the foundation for dynamic filtering and controlled result sets in later parts of the lesson.
Updating a Data Virtualization Endpoint
When you publish a Data Virtualization workspace, any changes made later to its endpoint settings in FME Flow will set the workspace status to Needs Updating.
When this happens, download the workspace again in FME Workbench so it reflects the new configuration. The new parameters will appear in the reader, ready to be used in your workflow before republishing to FME Flow.
1. Add Query Parameters to an Existing Endpoint
In FME Flow, open the Data Virtualization EnvironData API and go to the Endpoints tab. Select the GET /wildfires endpoint, then open the Parameters tab.
Next to Query Parameters, click Add. Create two query parameters: limit and status.
| NAME | TYPE | DESCRIPTION | REQUIRED |
| limit | Integer | Limit the number of returned results (between 1 and 1000) | No |
| status | String | Filter wildfire events by status (e.g., "active", "contained", "resolved" ) | No |
Keep both parameters optional so users can decide whether to include them in a request.
Optional parameters make the API more flexible, allowing requests that either use or skip filters.
2. Save to Update an Endpoint
Click Save to confirm the new parameters.
When you save, FME Flow will display a warning message indicating that the connected workspace must be updated.
This ensures that the workspace and endpoint stay synchronized.
Click Save again to continue.
3. Configure an Updated Data Virtualization Workspace
After updating endpoint metadata in FME Flow, the corresponding workspace must also be updated and republished.
Until this step is complete, the changes in the FME Flow web interface will not take effect.
To verify this, go to the Workspaces tab and find the GET /wildfires endpoint.
Its Workspace Status should display Needs Updating, meaning the workspace must be updated and republished before the changes become active.
Summary
With query parameters added, the EnvironData API can now accept input directly from user requests.
The endpoint metadata defines each parameter’s name, type, and location in the HTTP request, preparing the API for dynamic and flexible data access.
In the next part, you’ll update the workspace to implement the limit parameter and control the number of wildfire records returned in each response.
Part 2: Control Response Size with Limiting Parameters
In this part, the EnvironData Coordination Office sets up the limit query parameter to control how many wildfire records are returned in each API response.
This improves usability by preventing overly large result sets and giving users control over how much data is retrieved.
The parameter is implemented in FME Workbench by updating the workspace to read the input value and apply it to the SQLite query.
1. Update an Endpoint Workspace in FME Form
When endpoint metadata changes in FME Flow, the connected workspace must be updated or redownloaded to stay synchronized.
You cannot publish a workspace that is out of sync with its endpoint definition.
If FME Workbench is already open with the workspace loaded, click Publish. FME will detect that the endpoint metadata has changed and display the Update Reader dialog.
Select Update Reader to apply the new parameters before continuing.
If the workspace isn’t open, download it again from the Data Virtualization menu in FME Workbench. This automatically pulls in the updated endpoint definition from FME Flow.
2. Confirm New Parameters in the Reader
Once the workspace is updated, expand the GET /wildfires feature type in the Data Virtualization reader.
You should now see two new attributes: query.limit and query.status.
If these attributes don’t appear, confirm that:
- The endpoint parameters were saved correctly in FME Flow.
- The workspace was redownloaded or updated using Publish > Update Reader.
Next, you’ll modify the workflow to handle these parameters.
3. Run a Request in Workbench
When building or testing Data Virtualization workspaces, you can simulate API calls directly in FME Workbench.
To test locally:
- Open the mini-menu on the GET /wildfires feature type.
- Select Run Just This.
In the Translation Parameter Values window, the request template now has parameters to configure.
Update the placeholder values with test values. Replace “<integer>” with “3” and remove the “status” parameter entirely.
{
"method": "GET",
"parameters": {
"limit": [
"3"
]
},
"path": "/wildfires"
}This template imitates the request: http://<FME Flow>/api/EnvironData/wildfires?limit=3
You can also save this configuration for reuse. Select Save As Sample, and FME will automatically store it in a “Samples” folder in your local EnvironData directory.
Click Run. When the translation finishes, open the Visual Preview window to confirm that the query parameters appear as attributes with your test values.
4. Use a Query Parameter to Limit the Number of Results
The limit query parameter lets users control how many results are returned in a response.
Filtering data before it loads into the workspace is more efficient because it reduces processing time and memory usage.
Reader options such as WHERE clauses, SELECT statements, or database transformers (like InlineQuerier, SQLExecutor, or DatabaseJoiner) can all apply filtering logic before data is loaded.
This works especially well with request parameters, since values like query.limit or query.status can feed directly into a database query.
In this example, you’ll apply the limit directly within the FeatureReader.
Open it, go to Constraints, and under Max Features to Read, select From Attribute Values, then choose query.limit.
Click OK to apply.
5. Test the Limit Parameter
To test your changes, rerun the workspace using the sample request created earlier.
If prompted for Translation Parameter Values, select your saved sample.
When the translation finishes, open the cache on the fires port of the FeatureReader.
You should see that only three records were read, confirming that the limit parameter is working correctly.
If the parameter is missing or set to 0, all records will be returned by default.
Summary
The limit parameter now controls how many wildfire records are returned in each API response.
By filtering data before it loads, the workflow runs faster and handles large datasets more efficiently.
In the next part, you’ll use the status parameter to filter records based on their wildfire status, giving users even more control over their API requests.
Part 3: Customize Response Data with Filtering Parameters
In this part, the EnvironData Coordination Office adds the status query parameter to filter wildfire records by their current status.This lets users request only the data they care about and helps reduce unnecessary results.
Filtering works by comparing the user’s input to the status column in the fires table.
These updates make the EnvironData API more flexible, efficient, and easier to use.
1. Construct a WHERE Clause
The status query parameter allows users to filter results dynamically. To make this work, you’ll create a WHERE Clause that uses the value of query.status to filter the database table.
Add an AttributeCreator between the Reader and the FeatureReader. Make space on the canvas if needed to maintain a clear layout.
Open the AttributeCreator and create a new output attribute called WHERE Clause.
For its value, click the drop-down and select Conditional Values….
In the Conditional Value Definition window, add a condition that checks whether query.status has a value:
| Logic | Left Value | Operator | Right Value |
| query.status | Attribute Has a Value |
Set its value to: "status" = '@Value(query.status)'
In the next row, create another condition:
| Logic | Left Value | Operator | Right Value |
| query.status | Attribute is missing |
This time, do not set a value.
Click OK to apply the change.
The final AttributeCreator should look like this.
OK to save.
2. Apply the WHERE Clause
Now that the WHERE clause attribute exists, connect it to the database query.
Open the FeatureReader parameters.
In the Constraints section, set the WHERE Clause parameter to use the newly created attribute.
Click OK to save and close.
This ensures the SQL query dynamically filters results based on the user’s status input.
3. Run the Workspace with a Status Parameter
Next, test the status parameter using the same local testing workflow as before.
From the Run menu, select Rerun Entire Workspace.
This will refresh the request template.
This time, remove the “limit” query parameter and set the “status” value to “active”:
{
"method": "GET",
"parameters": {
"status": [
"active"
]
},
"path": "/wildfires"
}This template represents the request: http://<FME Flow>/api/EnvironData/wildfires?status=active
Save this as a sample for reuse (for example, get _wildfires-status.json).
4. Verify the Filtered Results
Click Run, then open Visual Preview on the GET /wildfires reader to confirm the updated attribute values.
You should see that query.limit is missing, and query.status shows as active.
Next, inspect the cache on the fires port of the FeatureReader.
You should see only two records, both with the status active.
This confirms the WHERE clause is working.
If you check dv_output.json, you’ll see the response body now contains only the filtered results matching the active status.
5. Test with Empty Parameters
Both status and limit are optional parameters, so the workspace must handle requests even when they are not provided.
Rerun the Entire Workspace once more, this time removing all parameters from the request template:
{
"method": "GET",
"parameters": {
},
"path": "/wildfires"
}Click Run to execute.
The full fires table should now be returned, which is the expected behavior when no parameters are provided.
You can verify this by checking the cache on the JSONTemplater or by reviewing the output file.
Save the workspace.
6. Publish to FME Flow
Once you’ve confirmed that filtering works correctly, publish the workspace to FME Flow to make your changes available through the live API.
In FME Workbench, click Publish.
After publishing, open FME Flow and navigate to the Workspaces tab.
Verify that the GET /wildfires endpoint shows a Workspace Status: Assigned.
This indicates the workspace is linked and ready to handle API requests using your new filtering logic.
7. Test from API Documentation
Open the Swagger documentation for your EnvironData API and locate the GET /wildfires endpoint.
Click Try it Out, then enter the following test values for the parameters:
- status= active
Try another test, this time adding a response size:
- limit=1
- status= active
However, if you were to try an invalid value, such as status: ACTIVE or limit: -1, the API would return an undescriptive error.
We’ll tackle what to do with bad data in the next step.
Summary
The status parameter now filters API responses based on wildfire status values, allowing users to request only relevant data.
By integrating the WHERE clause into the database query, the workspace retrieves only matching records, reducing unnecessary data.
The workspace is now published and ready for live requests.
In the next part, you’ll add validation and error-handling logic so the API can respond clearly when users provide invalid input.
Part 4: Improving API Reliability with Input Validation
Reliable APIs handle bad input gracefully.
In this part, you’ll test how the workspace responds to incorrect or missing parameters and add logic to fix or reject them before they reach the database.
Formatting issues can come from user mistakes or system differences. For example, one app might send uppercase status values while another uses lowercase. FME can automatically correct these before querying the SQLite database, ensuring consistent and reliable results across systems.
1. Create a New Status Code in FME Flow
Before adding validation logic, the API needs a clear way to communicate errors.
By defining a dedicated status code, you can make sure users receive useful feedback when something goes wrong.
In FME Flow, open the GET /wildfires endpoint.
Go to the Response tab and click Add Status Code. Configure it as follows:
| HTTP Status Code | 400 - Bad Request |
| Description | Invalid parameter value |
| Content Type | application/json |
| Input Type | Create Properties |
Responses don’t always need a predefined schema — you can define them with custom properties instead. This approach is useful for simple or unique responses and still shows clear examples in the API documentation.
Click Create next to Properties and add the following:
| Name | Type |
| ErrorMessage | String |
Save the endpoint.
2. Update the workspace
Whenever endpoint metadata changes, the workspace must be updated to stay in sync. This ensures new parameters or status codes appear correctly in your workflow.
In FME Workbench, open the workspace and update the reader:
- Go to Publish > Update Reader, or
- Redownload the workspace from FME Flow.
This ensures the workspace is in sync with the new endpoint definition.
(See Part 2 if you need to review these steps)
3. Add Conditional Logic for the Status Parameter
The status parameter filters wildfire records based on their current condition. To make sure users can only request valid statuses, you’ll use a TestFilter to define which inputs are accepted.
The TestFilter transformer checks each feature against one or more conditions and routes it based on the result.
Add a TestFilter to the workspace, make space if needed, and connect it after the GET /wildfires feature type.
Open the TestFilter to configure it.
In the fires table, valid values for status are active, contained, and resolved. Because the parameter is optional, leaving it blank is also valid.
Double-click the If row to open the Test Conditions window, then create the following tests:
| Logic | Left Value | Operator | Right Value |
| query.status | = | active | |
| OR | query.status | = | contained |
| OR | query.status | = | resolved |
| OR | query.status | Attribute Is Missing | |
| OR | query.status | Attribute Is Empty String |
Add all tests, set the Output Port to Valid Status, and click OK.
Rename the final Else Output Port to Invalid Status to catch unexpected values.
Click OK to save.
The TestFilter now has two output ports. Connect the Valid Status port to the AttributeCreator.
4. Normalize Input with StringCaseChanger
Some users may enter values in different cases — for example, ACTIVE instead of active. Since the database query is case-sensitive, we’ll fix these differences automatically before validation.
The StringCaseChanger transformer modifies the capitalization of attribute values, helping standardize user input before further processing.
Add a StringCaseChanger to the canvas. Connect it between the GET /wildfires feature type and the TestFilter.
Open the StringCaseChanger and in Selected Attributes, expand query and select status.
Click OK. Beside Case Change, select “lowercase”.
Now, any uppercase or mixed-case input will automatically be converted to lowercase before reaching the TestFilter.
To confirm, test the workspace with an invalidly cased value:
{
"method": "GET",
"parameters": {
"status": [
"ACTIVE"
]
},
"path": "/wildfires"
}This template represents this request: http://<FME Flow>/api/EnvironData/wildfires?status=ACTIVE
Run the request.
Because the database stores status values in lowercase, the workspace would normally reject this request. With the StringCaseChanger, the input is converted and now passes validation successfully.
If an input can’t be fixed automatically — such as a misspelled or unknown value — the workspace will treat it as invalid.
In the next steps, you’ll add logic to return a clear error message in those cases.
5. Validate the Limit Parameter
Next, we’ll verify the limit parameter to prevent requests that return too much data or invalid values.
The Tester transformer checks for specific conditions and is ideal for numeric or range-based validation.
Add a Tester to the canvas and make space if needed.
Create the following test clauses:
| Logic | Left Value | Operator | Right Value |
| query.limit | Type Is | Integer | |
| AND | query.limit | In Range | [0,1000] |
| OR | query.limit | Attribute Is Empty String | |
| OR | query.status | Attribute Is Missing |
These clauses ensure the user doesn’t send invalid data to the limit parameter, which could otherwise cause a database error.
6. Return an Descriptive Error Message
When users send invalid values that can’t be corrected automatically, the API should return a clear, consistent response. This improves error handling and helps clients understand what went wrong.
The AttributeCreator transformer lets you define response attributes directly in the workspace.
Add a new AttributeCreator to the canvas. Connect it to both the Tester (Failed) port and the TestFilter (Invalid Status) port.
Open the AttributeCreator and configure the following output attributes:
| Output Attribute | Value |
| response.status_code | 400 |
| response.body.content | {"ErrorMessage":"Invalid parameter value"} |
| response.body.content_type | application/json |
Review the parameters.
For successful (200) responses, we used a JSONFormatter to build the response dynamically.
This time, we’re setting a static message directly in the AttributeCreator, which is best for short, simple responses.
Click OK, then connect the AttributeCreator output port to the http_response writer feature type.
7. Test Invalid Responses
Now that your validation and error handling are in place, test how the workspace reacts to different types of bad input.
Try rerunning the workspace with several invalid parameter cases:
- A misspelled value (e.g., status="oepn")
- An unexpected type (e.g., limit="ABC")
- An invalid value (e.g., status="closed")
Example request:
{
"method": "GET",
"parameters": {
"status": ["CLOSED"]
},
"path": "/wildfires"
}This template represents the request:
http://<FME Flow>/api/EnvironData/wildfires?limit=3&status=CLOSED
Run the workspace and open the dv_output.json file to confirm that a 400 status code and error message are returned.
Save the workspace.
8. Republish to FME Flow
After completing your updates, publish the workspace to FME Flow so the changes take effect.
This ensures the endpoint uses the latest version of your workspace logic, including validation, case correction, and error handling.
In FME Workbench, click Publish.
Once published, open FME Flow and go to the Workspaces tab.
Verify that the GET /wildfires endpoint now shows Workspace Status: Assigned. This means your workspace is correctly linked and ready to handle live API requests.
9. Test Requests in Documentation
Finally, use the Swagger documentation or another API client to test the endpoint with different parameters.
In Swagger, open the GET /wildfires endpoint and click Try it Out.
Enter the following sample values:
- limit: 2
- status: RESOLVED
For example, test the results for the request: http://<FME Flow>/api/EnvironData/wildfires?limit=2&status=RESOLVED
Click Execute to send the request and review the response.
You should see two results that match the resolved status, confirming that your filters and limits are working correctly.
Next, test an invalid data type:
- limit=ABC
This time, FME Flow returns an error message before the request runs. This happens because the limit value was defined as an integer when the parameter was created, and the input doesn’t match that type.
Test a value outside of your defined range to confirm your custom error handling:
- limit=1001
Finally, test a combination of valid and invalid values to complete the tests:
- limit=2
- status=closed
The invalid value should trigger a 400 Bad Request error along with your custom message.
Summary
With validation, case normalization, and error handling in place, the EnvironData API is now more reliable and user-friendly.
It can fix common input issues, validate parameters before querying the database, and return clear messages when something goes wrong.
Together, these improvements make the API easier to use, integrate, and maintain.