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 endpoints that use manual responses, which return the same static response every time, workspace responses 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:

• Results that change based on request parameters

• Data is fetched live from external sources

• To process uploaded or downloaded files

• Responses that adjust to user input or real-time data

How Workspace Responses Work

When someone calls an API endpoint, FME runs a workspace in the background to handle the request. The workspace can get data, apply filters, run analysis, or format results. Once it’s done, 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 created in FME Flow.
2. Authoring: The workspace is downloaded to FME Form for workflow authoring.
3. Publication: The finalized workspace is uploaded back to FME Flow. 

Once published, the workspace can handle incoming API requests.

Documentation may change rapidly and not reflect the current build. This article was written with FME 2025.1.2 b25630.

Learning Objectives

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

• Develop and manage workspace endpoints.
• Create and apply schemas.
• Build workspaces with the Data Virtualization Reader and Writer.
• Use Input Templates for testing Data Virtualization workspaces.

Step-by-Step Instructions

You’ll build the GET /wildfires endpoint for the EnvironData API. It will connect to a SQLite database, query live wildfire data, and return results in JSON format. By the end, you’ll have a working endpoint that delivers real-time data through the API.

Part 1: Generate an Endpoint Workspace in FME Flow

The EnvironData team needs a GET /wildfires endpoint to share current wildfire data from their SQLite database. In this part, you’ll create the endpoint in FME Flow, define its HTTP method, response format, and link it to a workspace that retrieves and returns live data.

Understanding Schemas in Data Virtualization

The GET /wildfires endpoint returns data in a defined structure called a schema. Schemas ensure consistency in how requests and responses are formatted, making APIs easier to validate, document, and integrate with other systems.

• A response schema defines what the API sends back, including data types, required fields, and formatting. Each status code, such as 200 OK or 400 Bad Request, can use a different response schema.
• A request schema defines what the client must send, including required fields, data types, and formatting rules.

Using schemas improves reliability and usability by catching errors early. In this lesson, the response schema will mirror the structure of the SQLite fires table to ensure 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 the result of their request—whether it succeeded, failed, or requires attention. Each status code can include a schema that provides additional details about the response.

In FME Flow, you can set custom status codes for your endpoints. It’s best to use standard HTTP codes so they’re easy for others to understand, such as: 

• 200 OK – Request succeeded and returned data.
• 400 Bad Request – Request is invalid or missing something.
• 404 Not Found – The resource doesn’t exist.
• 500 Internal Server Error – Something failed on the server (for example, a workspace error).

These codes help users quickly see if the API is working as expected or if something needs fixing.

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

2. Create the Endpoint Schema

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” toggles as unselected. 

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

3. Create a Tag

Switch to the Endpoints tab. 

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

Click the Manage Tags (1) button to open the tag management dialog.

Click Create (2) and enter parameters (3) for a new tag:  

• Tag Name: events
• Description: Climate, disaster, and weather event data

Click Create to create the events endpoint tag. 

You should now see an events tag. Click Close to finish. The new events tag will be listed. 

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: 

• Path: wildfires
• Operation: GET
• Summary: List wildfire events
• Description: Returns an array of reported wildfires
• Tags: events
• Inherit API Setting: Enabled

5. Determine the Endpoint Response

Navigate to the Response tab. 

The Response Type determines whether 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 API response includes a status code that indicates the result of the request. The GET /wildfires endpoint should normally return wildfire data, but if something goes wrong—such as invalid input, missing data, or a database error—it will return a different response.

Defining status codes for both successful and error cases makes the API easier to understand and reduces troubleshooting.

To add one, click Add Status Code.

Most endpoints should have at least one success status code. Successful responses use codes in the 2xx range.

For this lesson, we will define a 200 OK status code to show that a GET /wildfires request successfully retrieved and returned data in the WildfireResponse schema.

• HTTP Status Code: 200 - OK
• Description: Successful
• Content Type: application/json
• Response Structure: Use Schema
• Schema: WildfireResponse

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.

• HTTP Status Code: 204 - No Content
• Description: Could not find the requested resource

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

After creating the endpoint, the Workspace Status will appear as Unassigned. This is expected, since the endpoint is not yet complete. Because the response type is set to Workspace, you still need to create and author the workspace before the endpoint can run.

7. Generate a Data Virtualization Endpoint Workspace 

Go to the Workspaces tab. This tab organizes all API endpoints into two groups: Workspace Endpoints and Manual Endpoints, giving you one place to manage responses.

Unlike regular workspaces stored in FME Flow Repositories, Data Virtualization workspaces are managed only through this tab. This keeps endpoint responses easier to organize, update, and maintain.

For example, the GET /about endpoint you created earlier appears under the Manual Endpoints tab.

The new GET /wildfires endpoint now appears under the Workspace Endpoints tab. Its status is shown as Unassigned because a workspace has not been generated yet.

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

Next, any selected endpoint(s) will be listed. Rename the workspace to WildfireEndpoints and Generate.

Once generated, the workspace will be assigned toGET /wildfires. The Workspace Status is now “Needs Authoring”.

At this point, the basic structure and configuration for the GET /wildfires endpoint are in place. 

Opening the endpoint in the Swagger documentation will display everything an end user needs to make the request and understand the responses.

However, if you try to call the endpoint now, it will return an error because the workspace has not been authored yet.

Summary 

You created a new workspace endpoint and defined how it connects to the GET /wildfires API method.
This step established the framework that links API requests to an FME Workspace, setting the stage for dynamic, data-driven responses.
In the next part, you’ll open the workspace in FME Workbench to begin authoring the logic that powers the endpoint.
 

Part 2: Author an Endpoint Response in FME Form 

In this part, you’ll move into FME Workbench to define how the GET /wildfires endpoint generates its response. By connecting to the internal SQLite database and shaping the output to match the expected schema, you’ll give the endpoint the logic it needs to return accurate, real-time wildfire data.

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

After connecting to FME Flow, you’ll be able to select an API. Choose the Environmental Impact and Response API (EnvironData) (2)

You can also select a location to download local workspaces and files (Select the root download directory). This will create a folder structure for your API: /<root path>/Data Virtualization APIs/<FME Flow instance>/Environmental Impact and Response API (EnvironData)/<endpoints> (3)

Select the WildfireEndpoints.fmw endpoint (4) and Download (5)

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

On the canvas, you’ll see a Data Virtualization Reader and a Writer. These are added automatically to every endpoint workspace. The reader represents the API request, and the writer represents the API response.

The Data Virtualization reader shows up as one or more feature types, depending on how many endpoints you selected in FME Flow. Since we only selected one, you’ll see a single feature type: GET /wildfires. If you expand it, you’ll find details about the request, such as the endpoint path (request.path) and any parameters.

The Data Virtualization writer always appears as one feature type called http_response. Its attributes are the same in every Data Virtualization workspace. It includes the basic pieces of any API response: status code, headers, and response body.

This workspace is just a starting point. You need to add transformers to tell FME how to handle requests and build the right response. The key steps are to:

• Work with any request parameters sent by the client
• Prepare the data so it matches the response schema
• Send the output to the right status code, depending on success or failure

With this logic in place, the endpoint will return clear and properly formatted responses every time.

2. Run the Workspace

When building an FME workspace, it’s best to test with real data as you go. You’ll probably run the workspace several times during development. However, Data Virtualization workspaces are designed to run on API requests... but you can’t send live API calls straight to FME Workbench!

To test locally, FME Flow provides parameters that simulate real API requests. Open the mini-menu on the GET /wildfires feature type and click Run Just This.

The Translation Parameter Values window opens, where you can enter sample request data for testing.

Click Run, then check the cached data. For this simple GET request with no parameters, the only value you’ll see is the endpoint path (request.path).

4. Connect to a Data Source

In an endpoint workspace, the Data Virtualization Reader represents the API request, but it does not pull in real data. To return results, the workspace needs to connect to an actual data source. 

For the GET /wildfires endpoint, the source is an SQLite database.

Add a FeatureReader to the canvas and connect it to the GET /wildfires Reader. 

Open the FeatureReader and set the format to SQLite (1), choose the events.sqlite file as the dataset (2), then select the fires table under Feature Types to Read (3).

Run to This on the FeatureReader.

Inspect the fires output port. The SQLite fires data is returned.

5. Review the Output Template

Now that the data source is in the workspace, we can set up the workflow that builds the endpoint response. This means shaping the wildfire data so it fits the WildfireResponse format, along with the right status code, body, and headers.

Expand the Data Virtualization writer (http_response) to review the response attributes.

Not every attribute is required, but these ones are used most often:

• response.status_code: the status code the endpoint returns
• response.body.content: the data sent back to the client (defined by the schema)
• response.body.content_type: the format of the response, usually application/json

6. Test for Expected Data

Let’s start by looking at status codes and their responses.

The GET /wildfires endpoint should only return 200 OK if it finds data in the SQLite table. To verify this, add a check into the workflow that confirms if FeatureReader is returning data.

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

Open the Tester and add one Test Clause: 

• Clause 1:
  • Left Value:_matched_records
  • Operator: !=
  • Right Value: 0

This test passes if the FeatureReader finds at least one record.

Run the workspace to the Tester to confirm the data exists on the Passed port. 

The Tester confirms data is in the fires table. 

7. Format Data into Schema

Remember, a 200 OK response must return data in the WildfireResponse schema. So, we need to transform the SQLite fires data to match this schema.

The JSONTemplater can take attributes and values and turn them into JSON. It’s especially useful for shaping endpoint responses to fit a schema.

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

Inside the JSONTemplater parameters, click the Sub Template (1). Use the + button to insert a row (2). In the new row, rename the port as “WILDFIRES” (3). Click the ellipsis on the WILDFIRES port to open the Template text editor (4).  

In the WILDFIRES Template Expression text editor, enter the WildfireResponse schema:

{
            "severity": "<string>",
            "cause": "<string>",
            "location": "<string>",
            "id": "<string>",
            "confirmed": "<boolean>",
            "status": "<string>"
         }

Notice this template has placeholders for the values, you will need to update those later. For now, click OK to close the text editor.

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

[
fme:process-features("WILDFIRES")
]

This template will contain the WILDFIRES array. Click OK to close the editor.

Update the Output Attribute Name to response.body.content (one of the expected response attributes on the Data Virtualization writer).

Click OK to close the JSONTemplater. 

The new WILDFIRES port will be added to the JSONTemplater. Connect the FeatureReader fires output port to the JSONTemplater WILDFIRES input port. 

Once connected, reopen the JSONTemplater and open the Sub Template (WILDFIRES) again.

Replace the placeholders (e.g., <string>) with FME feature attributes. You can find these attributes in the left-hand menu and either double-click or drag them into the template.

When editing a JSON template, don’t add quotes or extra formatting — FME will handle that automatically.

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

Do this for the whole schema, or copy and paste the schema below. In the end, every value in the Template Expression should use FME feature attributes.

{
            "severity": fme:get-attribute("severity"),
            "cause": fme:get-attribute("cause"),
            "location": fme:get-attribute("location"),
            "id": fme:get-attribute("fire_id"),
            "confirmed": fme:get-attribute("confirmed"),
            "status": fme:get-attribute("status")
         }

Review the completed template.

The response schema isn’t the same as the SQLite fires table — and that’s normal in API design. For example, our schema uses id, but the database table has fire_id and hazard_id. Since only fire_id matters for users, map it to id in the response.

Save and close the JSONTemplater, then run the workspace and check the results.

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

The response.body.content attribute now shows a list of wildfires, formatted to the WildfireResponse schema. 

8. Create Status Code and Response Body Attribute

Along with response.body.content, the Data Virtualization writer also needs values for response.status_code and response.body.content_type. We’ll create these attributes to complete the workflow for the 200 response.

Add an AttributeCreator to the canvas and connect it to the JSONTemplater. Open it and create two new attributes. The first will set the status code, and the second will define the content type:

• Output Attribute: response.status_code
  • Value: 200
• Output Attribute: response.body.content_type
  • Value: application/json

Tip: When building API workspaces, you’ll often need the same attributes. To save time, create a Parameter Preset. This lets you 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. 

Some attributes will appear in green, including response.status_code, response.body.content, and response.body.content_type. These are the attributes you created in the workspace. Remember that not every response needs every attribute.

Save the workspace. Once saved, run the entire workspace. 

When the translation is finished, open the output text file to see the full API response. The file is saved in the local root directory you set up in Step 1, for example:

/<root path>/Data Virtualization APIs/<FME Flow instance>/Environmental Impact and Response API (EnvironData)/WildfireEndpoints

Go to the Output folder to find it.

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

This file shows the full endpoint response in JSON format, including the status and body. It matches the output template we set up earlier, which confirms the workflow for the 200 OK response is working.

10 . Author for Alternate Status Code

For the GET /wildfires endpoint, we defined two status codes in FME Flow: 200 OK and 204 No Content.

• 200 OK is returned when the database query finds records.
• 204 No Content is returned when no records are found.

The Tester already checks whether the FeatureReader returns data. If data is found, the workflow goes to the JSONTemplater and returns 200 OK. If no data is found, we need to return 204 No Content instead.

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

Open the AttributeCreator_2 parameters to set up a new status code.

• Output Attribute: response.status_code
  • Value: 204

The 204 No Content response does not have a schema, so no response body is needed.

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

Save the workspace. 

11. Publish the Data Virtualization Workspace to FME Flow

To finish creating the Data Virtualization endpoint, publish the workspace to FME Flow.

In FME Workbench, go to the ribbon menu and choose Publish. The publishing wizard for Data Virtualization workspaces is a little different from standard ones, so check that the default API and workspace name are correct.

Make sure to upload the events.sqlite file. With Upload data files selected, click Select Files… 

To save the events.sqlite file to FME Flow, Click on Select Location… (1). Click Upload to a shared resource folder (2), then select the “Data” folder to expand. Click New Folder (3). Create a new folder called “EnvironData” (4). 

Return to the publishing wizard and publish. 

12. Confirm Workspace Status in FME Flow

In FME Flow, open the EnvironData API. Go to the Workspaces tab and refresh if needed. Find the GET /wildfires endpoint and review its details. The Workspace Status should show Assigned with a green check mark. This means a workspace has been published for the endpoint and the metadata hasn’t changed since publishing.

But this only confirms that the workspace is connected. It doesn’t confirm the endpoint is returning the right response. To check that, we need to 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

Summary 

You created a new workspace endpoint and defined how it connects to the GET /wildfires API method.

This step established the framework that links API requests to an FME Workspace, setting the stage for dynamic, data-driven responses.

In the next part, you’ll open the workspace in FME Workbench to begin authoring the logic that powers the endpoint.

Next Lesson: Enhancing Data Virtualization Endpoints with Parameters