Working with OpenAPI Specification Files in Data Virtualization

Files

CityGov.json
- 6 KB
- Download

Introduction

OpenAPI Specification (OAS) files provide a standardized, machine-readable format for describing REST APIs. These specifications improve consistency, simplify integration, and support automated documentation and testing. FME Flow's Data Virtualization feature supports both importing an existing specification to define a new API and exporting an existing API configuration as an OpenAPI-compliant JSON file. Note that FME does not currently support YAML OAS files.

When an API is created or imported into FME Flow, Swagger documentation is automatically generated. This documentation serves as a visual and interactive reference, detailing the API’s structure, endpoints, request parameters, response schemas, and security settings. It also supports testing API calls directly within the browser, which is useful during development and integration.

What's Inside an OpenAPI Specification File

An OAS includes:

API Metadata (title, description, version, etc.)
Paths
Operations
API Components (schemas, responses, parameters, request bodies, headers, examples)
Tags

An OAS does not include:

Access management and security
Workspaces
Data sources
Endpoint behaviour (asynchronous, caching, job expiry, etc.)
Any other dependencies specific to FME Flow and Data Virtualization.

When to Import an Existing OpenAPI Specification (OAS)

Data Virtualization APIs can be created from scratch or from an OAS file. Importing an OpenAPI spec is useful when:

Migrating existing APIs from another platform or version
Standardizing across teams using a shared spec
Using AI to generate a custom OpenAPI
Aligning with industry standards, such as in geospatial or smart city systems
Prototyping quickly using prebuilt definitions
Collaborating across teams with consistent API structures

After importing, you can connect endpoints to FME workflows and configure responses to serve live data. This method saves time and ensures consistency when working with shared or published API definitions.

Learning Objectives

After completing this exercise, you will be able to:

Import an OpenAPI Specification to define an API
Export a Data Virtualization API definition as an OpenAPI file to use in the OpenAPICaller

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.

Step-by-Step Instructions

This exercise demonstrates how to use an OpenAPI Specification to define a Data Virtualization API in FME Flow. You will begin by reviewing a sample OAS file, then import it to automatically generate an API configuration. You will also explore how to export an existing API as an OAS file, which can then be used in tools such as Postman and FME Workbench. This process supports faster prototyping, easier collaboration, and consistent API documentation across systems.

Part 1: Import an OpenAPI Specification

In this part of the tutorial, you will learn how to import an existing OpenAPI Specification (OAS) into FME Flow to create a Data Virtualization API. This approach reduces manual setup by generating the API structure automatically, including endpoints, parameters, and metadata.

1. Review the OpenAPI Specification File

We will start with a preconfigured OAS file: CityGov.json. To familiarize yourself with the OAS, open the CityGov.json file using a text editor, such as Notepad++. This JSON document organizes information about multiple departments in a municipal government.

2. Import to FME Flow

Open FME Flow in a browser and navigate to the Data Virtualization page. Select Import.

In the Import dialog, the Namespace should describe the API, as it will become part of the URL. Enter OpenGovData for Namespace, then select the CityGov.json file.

Click Upload to import the OpenAPI file into FME Flow.

3. Review Swagger Documentation

After the CityGov.json file has been successfully imported, the API Details page for the Data Virtualization API opens. This page provides a summary of key information about the API and allows you to manage its settings.

Additional configurations like Caching, Async Processing, Job Expiry, Queues, and Security can be added and updated after import.

4. Review Documentation

To view the API documentation, go to the API Details section and select View Documentation.

This will open the Swagger documentation in a new tab.

Swagger documentation has been automatically generated based on the imported OAS. Expanding each endpoint allows users to view imported details such as required parameters, possible responses, and associated schemas.

localhost_fmeserver_swagger-ui__api=f61a9c88-652c-4377-b192-6398ed0e6321(High Res Flow).png

At this point, making requests from the Documentation or another Client to the imported API will not be successful. This is because the underlying workflows that generate responses have not been configured yet. To make imported OAS files interactive in FME Flow, generate and author responses for each endpoint.

Part 2: Export an OpenAPI Specification

FME Flow supports exporting a Data Virtualization API as an OpenAPI Specification in JSON format. This export can be used to share the API's structure and definition with other teams or to load the API into external tools such as API clients and testing platforms.

This exercise will demonstrate using an exported OAS file in the OpenAPICaller in FME Workbench.

For full migrations between FME Flow environments, it is recommended to use an FME Flow Project instead. Project files include not only the OpenAPI Specification but also all related components and dependencies, such as workspaces, resources, and schedules, ensuring a complete and portable deployment.

1. Export a Specification

Open FME Flow in a browser and navigate to the Data Virtualization page. Select the City Government Services API and use the Actions menu to find Export OpenAPI Specification.

The JSON file will automatically download to your computer. Open the JSON file to inspect.

2. Import into FME Workbench

One of the most useful applications of the OAS file is for configuring requests in clients. The OpenAPICaller supports direct import of OAS JSON files.

Open a new workspace in FME Workbench. Add a Creator and OpenAPICaller to the canvas.

In the OpenAPICaller, use the Select button to Import.

In the Specification, find the downloaded JSON file for the City Government Services API.

3. Review Endpoints

The Select Endpoints window lists all the API endpoints included in the Specification, along with their parameters and requirements.

Choose one and select Import Request Parameters.

The endpoint then auto-populates the OpenAPICaller parameters, leaving only the values for configuration.

Once configured, the OpenAPICaller also supports Test Requests directly inside the transformer. This is a helpful tool for validating requests while authoring workflows.

However, because we haven’t configured the endpoint responses for the City Government Services API in FME Flow, any requests made from the OpenAPICaller will be unsuccessful.

For more information, see Getting Started with the OpenAPICaller.

4. Import to Postman

Postman is a widely used third-party tool for API development and testing. With a free account, you can import and work with OpenAPI Specifications directly in Postman. It is especially useful for testing client requests while developing a Data Virtualization API or building workflows that rely on that API.

Open Postman from your desktop and select the Import button.

Find and select the downloaded City Government Services API OAS file.

Choosing "Create a Postman Collection" imports only the requests for testing and usage, without retaining the original OpenAPI structure. Selecting "OpenAPI 3.0 Specification with a Postman Collection" imports both the spec and a synced collection, allowing you to view, edit, and manage the spec within Postman. For basic testing, choose the Postman Collection.