Creating a PUT Endpoint in a Data Virtualization API

Introduction

Data Virtualization APIs in FME Flow support not only reading data but also receiving and applying changes to existing records. PUT endpoints allow external clients to update a specific resource by replacing its current content with new data.

Unlike POST, which creates a new record, PUT updates an existing one. The target resource is identified by a unique ID in the URL path, and its contents are replaced with the data provided in the request body. This combination of a URL-embedded identifier and a structured body payload makes PUT well-suited for update workflows where a client needs to modify a specific record by reference.

Learning Objectives

After completing this lesson, you will be able to:

• Add a PUT endpoint with a path parameter
• Configure a request body schema for update operations
• Read both path parameter and body attributes in a workspace
• Check whether a target record exists before updating it
• Return appropriate HTTP response codes (200, 400, 404)

Step-by-Step Instructions

In this exercise, the EnvironData Coordination Office wants to allow authorized users to update existing wildfire records in their system. They will create a PUT /wildfires/{id} endpoint in their EnvironData API. When a client submits updated wildfire data, the workspace will:

• Validate that all required fields are present in the request body
• Verify that the targeted wildfire record exists in the database
• Replace the existing record with the new data
• Return a 200 OK on success, a 400 Bad Request if required fields are missing, or a 404 Not Found if the record does not exist

1. Create a Schema

Navigate to the Data Virtualization Environmental Impact and Response API in FME Flow. Open the Schemas tab.

Click Create to define a new schema.

Name the schema "WildfireUpdateRequest". For the Description, enter "Wildfire update request body."

For JSON Type, click Object.

Click Create next to Object Properties. Enter the following values, clicking Create again after each property:

Because PUT replaces the entire resource, the required fields mirror those of the original WildfireRequest schema. Optional fields like cause and severity may be omitted, but mandatory fields must be present for the updated record to remain valid.

When complete, click Create.

2. Create an Endpoint

Navigate to the Endpoints tab. Click Create to begin the PUT endpoint.

In the Endpoint Details, enter the following:

The {id} in the path is a path parameter. It tells the endpoint which wildfire record the client wants to update. FME extracts this value from the URL at runtime and makes it available as an attribute in the workspace.

3. Configure the Path Parameter

Because the path contains {id}, a new Path Parameters tab is now available. Navigate to it.

Path parameters identify the specific resource to be updated. Without them, the endpoint would have no way to determine which record to modify.

Configure the path parameter with the following values:

4. Configure the Request Body

Navigate to the Request Body tab.

Like a POST request, a PUT request includes a body carrying the updated resource data. Enable Required. Without a body, there is nothing to update.

Configure the remaining request body settings:

5. Configure the Response

Navigate to the Response tab.

For Response Type, click Workspace. Leave Inherit API Job Queue and Inherit API Job Expiry Time enabled.

Click Add Status Code to define response codes. Add three status codes.

First, define a 200 – OK status code, which will be used when the record is updated successfully:

Add a second status code, 400 – Bad Request, for requests missing required fields:

Add a third status code, 404 – Not Found, for requests targeting a record that does not exist:

The 404 status code is unique to endpoints that target a specific resource. If a client references an ID that does not exist in the database, returning 404 is more informative than a generic error.

Click Create to save the endpoint.

6. Assign a Workspace

Navigate to the Workspaces tab. The new PUT endpoint is listed with Workspace Status as "Unassigned".

Click the PUT /wildfires/{id} endpoint and expand the Endpoint Actions menu. Click "Generate Workspace". Name the workspace "UpdateWildfire.fmw".

Once assigned, the Workspace Status will update to "Needs Authoring".

7. Download Workspace

In FME Workbench, open the Data Virtualization menu and click the PUT /wildfires/{id} workspace.

The workspace opens with a Data Virtualization reader of type PUT /wildfires/{id}.

8. Use a PUT Template

Run the workspace.

In the Translation Parameter Values dialog, click Use Template and update the template with sample data:

{
   "body": [
      {
         "content": {
            "cause": "Lightning strike",
            "contact": "+1-555-618-5924",
            "lat": "50.73033",
            "long": "-120.33565",
            "reporter": "Sarah Chen",
            "severity": "high"
         },
         "contentType": "application/json",
         "name": "requestBody"
      }
   ],
   "method": "PUT",
   "path": "/wildfires/{id}",
   "pathParameters": {
      "id": "FIR-101"
   }
}

Then click Save As Sample and give the template a name, for example, put_wildfires_{id}-sample.json.

9. Parse the Body Contents

Add a JSONFlattener to the workspace and connect it to the PUT /wildfires/{id} feature type.

Double-click the JSONFlattener to configure its parameters. Under Source parameters, set JSON Document to the request.body attribute. Under Attributes to Expose, add all WildfireUpdateRequest schema properties: 

• cause
• contact
• lat
• long
• reporter
• severity

Click OK to close.

10. Check for Required Parameters

Add an AttributeValidator to the canvas and connect it to the JSONFlattener. Set the following parameters:

• Attributes to Validate:
  • contact
  • lat
  • long
  • reporter
• Validation Rule: Has a Value

Features that fail validation will be routed to the Failed port and return a 400 response.

Click OK to close.

11. Check Whether the Record Exists

Before updating, the workspace must verify that the target wildfire record exists. If it does not, a 404 response should be returned rather than attempting a silent no-op update.

Add a SQLExecutor to the canvas and connect it to the Passed port of the AttributeValidator.

Double-click the SQLExecutor to configure its parameters. Set the connection to the events SQLite database. In SQL Statement, enter:

SELECT fire_id FROM fires WHERE fire_id = '@Value(path.id)'

This query returns a _matched_records attribute indicating how many matching rows exist.

Connect the Initiator port to a Tester. Double-click the Tester and configure the following clause:

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

Features that pass this test (no matching record found) will return a 404 response. Features failing it (record exists) proceed to the update step.

Click OK to close.

12. Add a Datetime Attribute

For a PUT operation, updating the submission_date reflects when the record was last modified.

Add a DateTimeStamper to the canvas and connect it to the Failed port of the Tester from step 11 (where _matched_records ≠ 0, meaning the record exists).

Double-click the DateTimeStamper to configure its parameters. Set Include Fractional Seconds to No. Rename the Result attribute to submission_date.

Click OK to close.

13. Geocode the Coordinates

Add a Geocoder to the workspace and connect it to the DateTimeStamper.

Double-click the Geocoder to configure its parameters. Use a Geocoder Service of your choice, or use the free OpenStreetMap service for this example. Set Mode to Reverse and set the Latitude and Longitude parameters to the lat and long attributes respectively.

Click OK to close.

The Geocoder creates an _address attribute that will be written to the location column.

14. Filter the Attributes

Add an AttributeManager to the canvas and connect it to the Geocoder (or DateTimeStamper if you skipped the Geocoder). Double-click the AttributeManager and configure the following actions:

• Rename the following attributes:
  • Input Attribute: path.id
    • Output Attribute: fire_id
  • Input Attribute: _address 
    • Output Attribute: location
• Remove the following attributes:
  • request.path
  • request.body_file_path
  • request.body
  • request.content_type
  • _matched_records
  • _latitude
  • _longitude
  • lat
  • long

Click OK to close.

15. Update the Database Record

Add a FeatureWriter to the canvas and connect it to the AttributeManager. Double-click the FeatureWriter to configure its parameters. Set the connection to the events SQLite database.

Configure the following:

• Table Name: fires
• Table Handling: Use Existing
• Feature Operation: Update
• Match Columns: fire_id

The fire_id column is the WHERE clause key. FME will update only the row where fire_id matches the value from path.id.

Click OK to close.

16. Test for a Successful Update

Add a Tester to the canvas and connect it to the FeatureWriter's Summary port. Double-click the Tester and configure the following clause:

• Clause 1:
  • Left Value: _total_features_written
  • Operator: =
  • Right Value: 1

Click OK to close.

17. Format Successful Response Attributes

Add an AttributeCreator and connect it to the Tester's Passed port. Double-click the AttributeCreator and create the response attributes for the 200 status code:

• Output Attribute: response.status_code
  • Value: 200
• Output Attribute: response.body.content
  • Value: {"Message": "Record updated successfully"}
• Output Attribute: response.body.content_type
  • Value: application/json

Connect this AttributeCreator to the Data Virtualization writer, http_response.

The successful (200) workflow is now complete.

18. Format Not Found Response Attributes

Add another AttributeCreator and connect it to the Passed port of the Tester from step 11 (where _matched_records = 0). Double-click the AttributeCreator and create the response attributes for the 404 status code:

• Output Attribute: response.status_code
  • Value: 404
• Output Attribute: response.body.content
  • Value: {"ErrorMessage": "Wildfire record not found"}
• Output Attribute: response.body.content_type
  • Value: application/json

Connect this AttributeCreator to the Data Virtualization writer, http_response.

19. Format Failed Response Attributes

Add a final AttributeCreator and connect it to the Failed port of the AttributeValidator from step 10. Double-click the AttributeCreator and create the response attributes for the 400 status code:

• Output Attribute: response.status_code
  • Value: 400
• Output Attribute: response.body.content
  • Value: {"ErrorMessage": "Missing required parameters"}
• Output Attribute: response.body.content_type
  • Value: application/json

Connect this AttributeCreator to the Data Virtualization writer, http_response.

All three response paths are now complete.

20. Test the Workspace

Run the workspace with the sample template from step 8.

To confirm the update, open the events.sqlite database in the FME Data Inspector and verify the modified values appear on the targeted row.

Save the workspace.

21. Publish to FME Flow

Publish the workspace to FME Flow, uploading the Geocoder package if used.

Confirm the PUT /wildfires/{id} Workspace Status is now Assigned.

22. Test the Request from a Client

Find the PUT /wildfires/{id} endpoint in the EnvironData API Swagger documentation. Click Try it Out.

Set the id path parameter to an existing wildfire ID (for example, FIR-102). Replace the request body with the following sample:

{
   "severity": "extreme",
   "contact": "+1-555-903-4417",
   "cause": "Powerline failure",
   "reporter": "James White",
   "lat": "50.68035",
   "long": "-120.19706"
}

Click Execute.

A 200 – OK response confirms the PUT /wildfires/{id} endpoint is working correctly.

To test the 404 path, repeat with an ID that does not exist. To test the 400 path, omit a required field such as contact.

Additional Resources

Check the Getting Started with Data Virtualization page for detailed information, a tutorial series, and use cases.