Creating a Workspace Response for a Data Virtualization GET Endpoint

Introduction

Workspace response endpoints in FME Flow run an FME Workspace each time someone sends a request. This lets you return real-time data, which is useful when the data changes often or depends on user input.

Unlike manual endpoints, which return the same static response every time, workspace endpoints can connect to databases, apply logic, and return custom results. They’re ideal for data-driven or interactive APIs.

When to Use a Workspace Response

Workspace endpoints are essential in scenarios where:

• Responses need to adapt based on request parameters.
• Data must be retrieved dynamically from external sources.
• File uploads or downloads need to be processed.
• Response content changes based on user input or other real-time factors.

How Workspace Endpoints Work

Workspace endpoints link an API to an FME workspace. When someone sends a request, the workspace runs behind the scenes to handle it. It can fetch data, apply filters or changes, run analysis, and build a custom response based on the request. After that, FME sends the response back to the client.

Authoring a Workspace Response

Creating a workspace response means working with both FME Form and FME Flow. There are three main steps in the process:

1. Generation: The workspace is initially created in FME Flow.
2. Authoring: The workspace is downloaded to FME Form for workflow authoring, such as defining schemas, transformations, and logic.
3. Publication: The finalized workspace is uploaded back to FME Flow for deployment, allowing the endpoint to process live requests.

Data Virtualization is currently in technical preview within the 2025.1 beta and should not be used for production. Note that documentation may change rapidly and not reflect the current build. This article was written with FME 2025.1 b25562.

Learning Objectives

After completing this lesson, you’ll be able to:

• Develop and manage workspace endpoints.
• Create and utilize schemas.
• Operate the Data Virtualization Reader and Writer.
• Employ Input Templates for testing Data Virtualization workspaces.

Step-by-Step Instructions

In the following exercises, we will:

• Create the GET /wildfires workspace endpoint: 
• Connect to a SQLite Database containing hazard data
• Use Schemas and the JSONTemplater to format the response

By the end of this lesson, you will have a fully functional workspace endpoint that integrates real-time database queries with API responses.

Part 1: Generate an Endpoint Workspace in FME Flow

The EnvironData team needs a GET /wildfires endpoint to share real-time wildfire data from an internal SQLite database. This gives users direct access to current information without relying on email updates or manual work.

In this lesson, you'll build on the EnvironData API by creating a new endpoint in FME Flow. You'll define the HTTP method, status code, response format, and other key settings. The endpoint will be configured to run an FME Workspace that queries the database and returns the latest data.

Understanding Schemas in Data Virtualization

The GET /wildfires endpoint will return data that follows a specific schema. Schemas are key to Data Virtualization APIs because they standardize how requests and responses are structured. They help with data validation, clear documentation, and smooth integration.

• Response Body Schemas define what the returned data should look like—data types, required fields, and formatting. Each HTTP status code (like 200 OK or 400 Bad Request) can have its own schema.
• Request Body Schemas define what clients must send to the API, including required fields, valid data types, and rules like length or format checks.

Using schemas improves API usability and reliability. They make the API easier to work with by enforcing clear rules and helping catch errors early.

For this endpoint, the response schema will match the structure of the SQLite fires table to make sure the data is returned in the correct format.

Delivering Responses with Status Codes

A status code is a number in the API response that tells the client what happened with the request. It shows if the request worked, failed, or needs more action. Each status code may also include a response with more details or a specific schema.

FME Flow lets you customize status codes through endpoint settings and workspaces. But it's best to stick to standard HTTP codes so others can understand and use your API more easily. Common codes include:

• 200 OK – The request worked and returned data.
• 400 Bad Request – The request was wrong or missing something.
• 404 Not Found – The resource doesn’t exist.
• 500 Internal Server Error – Something went wrong on the server. FME uses this if a workspace fails unexpectedly.

These codes help users know what went wrong (or right) so they can fix issues or confirm the API is working.

1. Review the Data

The GET /wildfires endpoint will return data related to fire incidents and reports, drawn from a database table in SQLite. Before creating an endpoint, it's good practice to review the data source(s).

Download events.sql file provided in this article. To review the data, open FME Data Inspector and click Open Dataset. In the Select Dataset To View dialog, select SQLite as the Format and use the file explorer to select events.sqlite which can be found in the Downloads folder.

Select OK to finish. Select the table for fires and review the data. 

The table contains entries for 6 unique fire events. Consider which attributes and values would be useful to include in an API and those that might need to be omitted for privacy or efficiency.

We will create a workspace endpoint that allows clients to access a filtered view of this data over the web. 

2. Create the Endpoint Schema

The schema for the GET /wildfires response body will be based on the content of the SQLite fires table. 

In FME Flow, navigate to Data Virtualization > Environmental Impact and Response API. Switch to the Schemas tab, then click Create to author a new schema. 

In the Create Schema dialog, enter the following:

• Name: WildfireResponse
• Description: Wildfires response body. 

Next to Properties, select Create. Create a property for each of the following values: 

Leave the “Required” values as unselected. 

Click the Create button under the properties to publish the new WildfireResponse schema. 

3. Create a Tag

We will create a new tag for endpoints related to climate events, like wildfires and floods. 

Click the Manage Tags button to open the tag management dialog.

Click Create and enter parameters for a new tag:  

Click Create to create the events endpoint tag. 

Click Close to finish. 

4. Create a Workspace Endpoint 

With the event tag created, we can now create the GET /wildfires endpoint. Under Endpoints, click Create. 

In the Create Endpoint Details tab, enter the following values: 

5. Determine the Endpoint Response

Navigate to the Response tab. 

Response Type determines if the endpoint is workspace generated (dynamic) or manual (static). Select Workspace. 

The value of the Assigned Workspace remains “None” until we generate a workspace in later steps. 

In the Job Settings, leave all values default (Inherit API Job Queue and Expiry Time as enabled). 

6. Create Status Codes

Every endpoint response includes a status code that shows what happened with the request. The GET /wildfires endpoint should return data in the WildfireResponse schema, but if something goes wrong like bad input, missing data, or database issues, it may return a different response. It's good practice to create status codes that account for possible errors or unexpected results, even when they're not actual failures. This improves the API's usability and helps prevent unnecessary troubleshooting for end users.

To define a new status code, click on Add Status Code.

Unless an endpoint is intentionally left unauthored, most endpoints should have at least one configured success status code. Successful responses fall within the 2xx range. 

For example, we'll first define a 200 OK status code to indicate that a GET /wildfires request has successfully retrieved and returned data in the WildfireResponse schema.

After setting up the 200 OK status code, click Add Status Code again to define additional responses. 

Configure a 204 No Content status code. This will be returned when a GET /wildfires request is successful, but no matching data is found in the SQLite fires table.

Once the 204 status code is created, scroll to the top of Create Endpoint and click Create.

The new GET /wildfires endpoint will be added underneath the events tag. 

7. Generate a Data Virtualization Endpoint Workspace 

Still in FME Flow Data Virtualization Environmental Impact and Response API, select the Workspaces tab. 

The Workspaces tab groups all API endpoints into Workspace Endpoints and Manual Endpoints, giving you one place to manage API responses. Data Virtualization workspaces aren’t stored in FME Flow Repositories like regular workspaces. Instead, they’re managed only through this tab, making it easier to organize, update, and maintain endpoint responses.

For example, the GET /about endpoint (created in a previous lesson) is listed under the Manual Endpoints tab. 

The new GET /wildfires endpoint is listed under the Workspace Endpoints tab. 

Workspace Endpoints list information about the endpoint status, including its tags, last updated, and status. The GET /wildfires endpoint Workspace Status is currently “Unassigned” because we have not yet generated a workspace. 

To generate a workspace, select the GET /wildfires endpoint from the list. With the endpoint selected, use the Endpoint Actions drop-down menu to select Generate Workspace. 

A dialog opens to confirm the details of the workspace. Any selected endpoint(s) will be listed here. Rename the workspace to WildfireEndpoints.  

Once generated, note that the details of the GET /wildfires have been updated. The Workspace Status is now “Needs Authoring” and the new workspace (WildfireEndpoints.fmw) is listed. 

At this stage, we’ve defined the basic structure and configuration for the GET /wildfires endpoint. Reviewing the endpoint in the Swagger documentation will show all the necessary information an end user needs to understand how to make the request and interpret its responses. 

However, attempting to call the endpoint now via the Try it Out button would result in a generic 500 error, as a workspace has not yet been authored. 

The endpoint response still needs to be authored.

No more setup is needed in FME Flow to build the GET /wildfires response. The next steps happen in FME Workbench, where you’ll download and edit the WildfireEndpoints.fmw workspace to control how the data is fetched and returned.

Part 2: Author an Endpoint Response in FME Form 

In this part, you'll continue building the GET /wildfires endpoint by defining its response logic in FME Form. After downloading the WildfireEndpoints.fmw workspace from FME Flow, you'll customize it to control how the endpoint processes and returns data.

This includes using the Data Virtualization reader and writer, querying the internal SQLite database, and adding transformers to format the data to match the expected schema. These steps ensure the endpoint returns accurate, real-time wildfire data and connects the API to the live data source.

Understanding Input Templates

This part uses Input Templates to build and test the Data Virtualization workspace in FME Workbench. Input Templates are automatically generated JSON files that define the expected structure of both the request and response for a specific endpoint. These templates outline the key elements of an API request, including the HTTP method, request path, headers, and parameters.

Example template structure:

{
   "path": "/myendpoint/{pathparameter}",
   "pathParameters": {"mypathparameter": "<string>"},
   "headers": {"myheaderparameter": ["<string>"]},
   "method": "GET",
   "parameters": {"myqueryparameter": ["<string>"]}
}

These templates can be used with the Data Virtualization reader to simulate real API calls. By filling in the placeholders with sample values, authors can test how the workspace behaves with different inputs without needing to send actual requests to the API.

Input Templates are essential for:

• Testing how request parameters are handled
• Validating response formatting
• Debugging workspace logic before deployment

1. Open a Data Virtualization Workspace in FME Workbench

Open FME Workbench. On the Start tab, click Data Virtualization (Also accessible from File > "Open from FME Flow Data Virtualization") 

The FME Workbench Data Virtualization wizard allows you to download endpoint workspaces generated in FME Flow for editing and updating in FME Workbench. To start, make sure your FME Flow Web Connection is selected (or create one if needed).

After connecting to FME Flow, choose or create a folder on your computer to store your in-progress Data Virtualization workspaces. Create a folder named “EnvironData” to keep your local endpoint workspaces organized.

Select the WildfireEndpoints.fmw endpoint then click Download.

A warning dialog will popup stating that the workspace must be republished to FME Flow for the endpoints to be updated. Click OK to close the dialog. 

The WildfireEndpoints.fmw workspace will open. All endpoint workspaces are automatically generated with a Data Virtualization reader and writer, which represent the API request and response, respectively.

The Data Virtualization reader appears on the canvas as one or more feature types, depending on the number of endpoints selected in FME Flow. Since only one endpoint was selected, the canvas contains a single feature type: GET /wildfires. Expanding this reveals key request details such as the endpoint path (request.path) and any defined parameters.

In contrast, the Data Virtualization writer always appears as a single feature type: http_response. Its schema is consistent across all Data Virtualization workspaces and includes the standard elements of an API response: status code, headers, and a response body.

The template workspace is just a shell, it’s up to the author to add the necessary transformers that handle incoming API requests and construct appropriate responses. The primary goal is to define workspace logic that:

• Handles request parameters sent by the client
• Filters, transforms, or structures data according to the defined response schema
• Directs the output to the correct status code, based on whether the request was successful or encountered issues

By building this logic into the workspace, you ensure that every API request returns clear, validated, and properly structured responses that are aligned with the design and expectations of your Data Virtualization API.

2. Run With Template

To build an FME workspace effectively, it's useful to work with real data during development. But Data Virtualization workspaces rely on API request input, and you can’t send live API calls directly from FME Workbench. To test locally, FME Flow provides input templates that simulate real API requests.

Use the mini-menu on the GET /wildfires feature type and click “Run Just This”. 

The Translation Parameter Values window opens where we can configure sample request data for testing. 

Select Run and inspect the cached data. For this simple GET request with no parameters, only the endpoint path will be present (“request.path”). 

4. Connect to a Data Source

In an endpoint workspace, the Data Virtualization Reader only represents the incoming API request. It doesn’t connect to the real data. To return actual results, we need to bring in the real data sources.

The next step is to build a workflow that reads from the SQLite database and formats the data to match the WildfireResponse schema. This makes sure the response is accurate, structured, and ready for the API.

To do this, we use the FeatureReader transformer. It lets the workspace access data during translation, based on the request input. This is important for API workflows, where the Data Virtualization Reader stands in for a regular reader. The FeatureReader uses request parameters to query the database at runtime and return customized results.

Add a FeatureReader transformer to the canvas and connect it to the GET /wildfires reader feature type. In the parameters, select SQLite as the Format. Select the events.sqlite file as the Dataset. 

In Feature Types to Read, click on the ellipsis, then select the fires table and click OK twice. 

Use Run to This on the FeatureReader’s mini menu, then inspect the fires output port. The SQLite fires data table is returned.

5. Review the Output Template

Now that the data source is in the workspace, we can build the workflow that creates the endpoint response. This means using transformers to format the wildfire data to match the schema set in FME Flow. That includes the right status codes, response body, and headers. This step makes sure the output meets the endpoint’s requirements and shows the data correctly to users.

To see what the response should look like, check the attributes in the Data Virtualization writer. The writer shows what attributes we need to create. 

Expand http_response to view the attributes that make up the API response data. 

Not all writer attributes are required, but there are a few that we will almost always create in the workspace: 

• response.status_code will have the value of one of the endpoint’s status codes. 
• response.body.content will contain the requested data in the format of the response schema. 
• response.body.content_type will contain the response data format, typically application/json. 

In FME Flow, navigate back to the Workspace Endpoints tab. This time, download the Output Template for GET /wildfires. 

Open it in a text editor. 

The Output Template shows what the endpoint's response looks like in JSON format. Note the parameters and status codes that we configured in FME Flow. 

• For the 200 status code, the 'body.content' values (severity, name, location, id) match the WildfiresResponse schema. 
• For the 204 status code, no properties or schema were assigned. 

As we build the Data Virtualization workspace for the GET /wildfires endpoint, our task is to set up these two status codes correctly and format the fires data into the JSON schema from the Output Template. This ensures our responses are properly structured and formatted to align with our API's design.

Return to FME Workbench. 

6. Test for Expected Data

FME can only return a 200 OK response for a GET /wildfires request if it finds data in the SQLite table. To make sure this happens, we need to check that the FeatureReader is correctly reading and returning the data.

Add a Tester to the canvas and connect it to the FeatureReader’s <initiator> port. 

Open the Tester and add one Test Clause: 

This test clause ensures that a feature will pass if the FeatureReader returns 1 or more records. 

Run the workspace to the Tester to confirm the data exits the Passed port. 

The Tester confirms that the endpoint request has successfully found data in the fires table and the workflow can proceed to the next steps of the 200 response workflow. In the next steps, we will format the ‘fires’ data into the expected response schema, WildfiresResponse.  

7. Format Data into Schema

Recall, the API documentation for a 200 status code returns the WildfireResponse schema.

Therefore, we need to transform the SQLite "fires" data to match this expected schema. 

The JSONTemplater is a versatile transformer capable of converting attributes and values into JSON format. This transformer is particularly effective for structuring endpoint response schemas within the workspace, making it an essential resource for formatting data precisely according to schemas.

Add a JSONTemplater to the canvas. Connect the Tester’s Passed port to the JSONTemplater’s Root port. 

Inside the JSONTemplater parameters, enable the Sub Template. Use the + button to insert a row. In the new row, replace the default Port value with WILDFIRES. 

Click the ellipsis on the WILDFIRES port to open the Template text editor.  

In the WILDFIRES Template Expression dialog box, build or copy the WildfireResponse schema:

Note that this schema can also be copied from the Swagger documentation or the output template file (response_template.json):

Paste the content into the Template Expression text editor.  

This template will not work as is. In the next steps, we finish the sub template by updating the placeholder values (e.g. “<string>”). For now, click OK to close the text editor.

Under Root Template, use the ellipsis to open the text editor for Template. 

In the editor, build or paste the following: 

This template format will format the templated WILDFIRES data in a JSON array. Click OK to close the ROOT Template Expression editor. 

Update the Output Attribute Name to response.body.content. Recall, response.body.content is one of the expected response attributes on the Data Virtualization writer.  

Click OK to close the JSONTemplater. 

The newly created WILDFIRES input port will appear on the JSONTemplater. Connect the FeatureReader fires output port to the JSONTemplater WILDFIRES input port. 

Once connected, reopen the JSONTemplater to finish the WILDFIRES sub template configuration. Open the WILDFIRES sub template by clicking on the ellipsis. 

Replace the placeholder text (e.g. “<string>”) with the corresponding FME Feature Attributes. FME Feature Attributes are located on the left-hand menu and can be double-clicked or dragged into the text body. When creating a JSON template, do not use any quotation marks or other formatting characters (FME applies them automatically). 

For example, replace the value for “severity” with fme:get-attribute(“severity”). 

Repeat the process for the entire schema, or copy and paste the schema below. The final Template Expression should have FME Feature Attributes for all the schema values. 

Review the completed template.

Note that the schema defined for the endpoint response does not exactly match the schema of the SQLite fires table. This is common in API design. Sometimes, attribute names need to be adjusted to improve clarity for end users or to meet the formatting requirements of another system or application.

For example, the WildfireResponse schema includes an attribute called id. However, the SQLite table contains two identifiers: fire_id and hazard_id. Since hazard_id is not relevant to end users, we can simplify the response by mapping fire_id to the id field. This makes the data more intuitive and tailored to what the client actually needs.

Save and close the JSONTemplater. 

Run the workspace to the JSONTemplater and inspect the results. 

Double-click the response.body.content attribute in Visual Preview to view the formatted response.  The JSON is not pretty-printed by default, click the ABCXYZ button in the bottom left corner and select JSON.   

The new response.body.content attribute contains a list of wildfires, formatted to the WildfiresResponse schema and populated with the SQLite fires data. 

8. Create Status Code and Response Body Attribute

In addition to the response.body.content, the Data Virtualization writer expects values for the status code (response.status_code) and content type (response.body.content_type). To finish the workflow for the ‘200’ response, we must create those attributes. 

Add an AttributeCreator to the canvas and connect it to the JSONTemplater. Open it up to create two response attributes. 

The first attribute will produce the status code: 

The second attribute will define the content type: 

TIP: When building endpoint workspaces, you’ll often create the same attributes. To save time, consider creating a Parameter Preset. This lets you quickly reuse your AttributeCreator settings in future workspaces.

9. Connect Data Virtualization Writer and Run Workspace

Connect the Output port of the AttributeCreator to the http_response writer. 

Notice that some, but not all, of the attributes are highlighted in green. These green attributes, such as response.status_code, response.body.content, and response.body.content_type, are the ones we created in the workspace. Remember, not every response requires all attributes to be filled. 

Run the entire workspace. The Translation Parameter Window will appear and prompt you to set a Destination Data Virtualization Folder. Within the EnvironData folder, create a new folder named “Responses”. 

Run. Upon completion, we can inspect the full API response. Navigate to the “Responses” folder. 

Inside the folder, open the dv_output.json file in a text editor. Inspect the result.  

This file includes the full endpoint response, including the status and the body, in JSON format. It's formatted just like the output template we looked at before, which confirms that we've successfully set up the workflow for the ‘200’ response code.

It's important to remember that while this file contains everything FME needs to generate an endpoint response, it is not what the end user will see. Since clients interact with the endpoint via an API client, they’ll receive this same information as an HTTP response rather than a text file. Later in the lesson, we will test making a request to this API endpoint.

10 . Author for Alternate Status Code

Data Virtualization authors are responsible for implementing the workspace logic that handles all status codes defined in the endpoint metadata. In FME Flow, we previously defined both a 200 – OK and a 204 – No Content status code for the GET /wildfires endpoint. 

The 204 response is intended to indicate: “Could not find the requested resource.”

To complete the endpoint workspace, we need to build logic that covers scenarios where no data is returned from the database query.

In the current workspace, the Tester transformer is used to evaluate whether the FeatureReader successfully retrieves any records from the SQLite fires table.

• If records are found, the data flows to the JSONTemplater, which formats the response for a 200 – OK status.
• If no records are found, we must direct the workflow to generate a 204 – No Content response instead.

This conditional branching ensures the API returns appropriate feedback based on the presence or absence of data, maintaining accuracy and consistency in how responses are handled.

To do this, add another AttributeCreator to the workspace and connect it to the Tester’s “Failed” port. 

Open the AttributeCreator_2 parameters to set up a new status code and response, using the settings from the FME Flow endpoint metadata.

Recall that for the '200' response, we configured a schema for the response. However, the ‘204’ response was not configured with a schema, therefore, we do not have to create a response body.

Connect the AttributeCreator_2 Output port to the http_response writer feature type. 

11. Publish the Data Virtualization Workspace to FME Flow

To complete the process of authoring a Data Virtualization Endpoint, the workspace must be published to FME Flow. 

But before publishing, save a local copy of the workspace. In the same location as the Templates folder, create a Workspaces folder.  Save the workspace. 

From the FME Workbench ribbon menu, select Publish. The publishing wizard for Data Virtualization workspaces is slightly different compared to standard FME workspaces. Verify the default API and the workspace name. Disable Upload data files, then click Publish to finish.  

12. Confirm Workspace Status in FME Flow

Open or return to FME Flow. Then navigate to the FME Flow Data Virtualization Environmental Impact and Response API. In the Workspaces tab, and refresh if necessary. Find the GET /wildfires endpoint and review its details. The Workspace Status has been updated to Assigned, with a green check mark. This confirms that a workspace has been published for this endpoint and no edits have been made to the endpoint metadata since last published. 

It does not, however, confirm that the endpoint workspace is returning expected response. To confirm the endpoint is successfully delivering the expected response, we can test the request from an API client. 

13. Test the Endpoint Request in Swagger Documentation

The endpoint can be tested from any API client that can reach FME Flow (Postman, HTTPCaller, etc.), but the easiest method for a GET request is from the Swagger documentation. 

If not already open, open the Swagger Documentation from the API Details tab then click View Documentation. Find the GET /wildfires endpoint and click to expand. Click Try it Out, then click Execute. You may be prompted for your username and password. 

Below, the response will appear. If successful, it will include a ‘200’ response and an array of wildfires.

Next: Enhancing Data Virtualization Endpoints with Parameters