By Amala P Chungath and Sivadarsana Unni

Introduction

API development practices continue to evolve, and IBM API Connect v12.1.0.0 reflects those changes with a modernized approach to designing, testing, and publishing APIs. The new IBM API Studio streamlines the API lifecycle, making it more developer-friendly, modular, and aligned with today’s best practices.

For teams that have worked extensively with v10 using API Designer, the shift to v12 brings powerful improvements in workflow, structure, and automation.

This blog guides you through the transition with clear, side-by-side comparisons and practical tips, showing exactly how familiar v10 workflows including the API creation, Product and Plan setup, publishing, and test execution, are reimagined in v12.

Purpose of this Guide

This guide highlights the workflow changes in API Connect v12 and demonstrates how to use them effectively. It focuses on:

• How workflows and assets have changed
• Why these changes were introduced
• How to replicate v10 practices in v12

Snapshots, recordings, and example workflows help you map your existing knowledge to the new environment with confidence.

Intended Audience

• API Developers and Integration Engineers

• Product Managers and API Architects

• DevOps Professionals working with IBM API Connect

• API Testers

Whether you are migrating from v10 or are new to API Connect, this guide provides a structured overview of how v12 modernizes API development.

Background

In API Connect v10, API Designer provided a visual, assembly-driven workflow with drag-and-drop policies, form-based editing, and simple local testing using the Test tab, Explorer, Try It, and the Local Test Environment (LTE) to validate APIs before publishing. While easy to use, this approach made versioning, maintaining large APIs difficult.

API Connect v12 introduces a project-centric, code-first model in IBM API Studio. All assets such as APIs, Products, Plans, Policies, Tests, and Environments are stored together in a single project. This brings clearer separation between specifications and policies, better lifecycle and version management, a modular YAML-based structure, and built-in support for structured API testing. It also aligns more closely with OpenAPI and modern development practices.

Overall, v12 moves from v10’s isolated, visual tools to a unified, project-based workspace that supports modular development, reusability, and version control.

Creating an API

API creation is one of the biggest areas where API Connect v12 changes the development workflow.
While v10 relied heavily on API Designer, v12 shifts to the project-based, code-first IBM API Studio, offering more structure, modularity.

This section compares how APIs are created in v10 vs v12, including what changed, what improved, and how testing differs.

v10 (API Designer) :

• Create: Add → API.
• Single YAML held everything.
• Authoring via form-based panels and a visual Assembly editor.

Simple, visual, and all-in-one.

v12 (IBM API Studio) :

• Project-based workspace where each API is developed, tested, and managed as part of a structured API project.
• Two separate files per API: an API metadata file (kind: api) and an API specification file (api-spec, OpenAPI YAML).
• Code-first authoring with UI assistance, enabling modular assets and better version control.
• The separation of metadata and spec is new compared with v10’s single YAML approach.

Step 1 : Create a New API Project

• Open IBM API Studio.
• Go to Home, then New API Project.

• Choose a storage option:
  • Repository (Connect to a GitHub repository to manage projects with version control.)
  • Local folder (Store projects on your system by setting up a local workspace)
  • Native storage (Store projects in the built-in storage provided by IBM API Studio.)
• The project is created with a clean folder structure where you can add APIs, policies, and tests.

Step 2 : Choose How to Create the API

Inside the project, select Add an API. IBM API Studio provides three creation options:

1. Create from Scratch : Enter API name, namespace, version, type (currently only REST is supported), and optional tags.

2. Import File : Upload an existing OpenAPI YAML or JSON file.

3. Load from URL : Fetch an OpenAPI definition from a remote URL.

Step 3 : Edit the API (Two Authoring Modes)

IBM API Studio generates two files for every API:

• API metadata file (kind: api)
• API specification file (api-spec)

You can edit the API using either mode:

• Form View : Configure general information, paths, operations, security, tags, components, documentation, policy sequence, URI schemes, CORS, and properties.
• Code View : Directly edit the YAML-based OpenAPI specification and policy sequence.

Users can switch between Form view and Code view at any time depending on preference.

Setting up Policies

Policy management in API Connect v12 is more structured and flexible than v10. While v10 applied policies mainly at the API level through API Designer, v12 supports multiple enforcement levels, reusable policy sequences, and both Code View and Form View, giving developers more control and scalability.

v10 (API Designer) :

• Policies were added per API using the Policy tab.
• Offered a wide range of built-in policies across logic, actions, security, transforms, AWS Lambda, and new AI integration policies such as OpenAI, Azure OpenAI, and Gemini.
• Policies could be grouped into sequences.
• Mostly visual and form-based, with optional YAML Source mode.
• Limited support for global or granular enforcement.

v12 (IBM API Studio) :

• Project-based structure with policies that can be applied globally, at the API level, or at specific scopes.

• Policies are reusable through policy sequences.

• Policy sequences introduce an execution order, ensuring consistent enforcement of multiple policies across different scopes.

• Policies can be authored in Code View (YAML) or Form View (UI).

Step 1 : Create a Policy or Policy Sequence Open IBM API Studio and select Add Policy Sequence inside the project. Choose a gateway type: DataPower Nano Gateway DataPower API Gateway webMethods API Gateway The editor adjusts based on the selected gateway and its supported policies. Enter basic details such as sequence name, namespace, version, tags, and API. A blank policy sequence file is created.

Step 2 : Add Policies 

IBM API Studio gives two options for adding policies:

• Option A : Code View
  • Write policies in YAML.
  • Define kind, metadata, spec, and other attributes.
  • Reference policies in the sequence using the format: $ref: namespace:policy-name:version
• Option B : Form View
  • Select and configure policies through a guided UI.
  • Configure parameters for each policy without writing code.
  • Policies are grouped into functional categories such as Logic, Actions, Security, and Transforms.

Step 4 : Apply Policy Sequences to APIs

• Once the policy sequence is ready, link it to an API or multiple APIs.
• In Form View, go to the Policy Sequence section in the API’s outline and add the desired policy sequence.
• In Code View, reference the sequence in the API metadata using:

policy-seq:

$ref: namespace:policy-sequence-name:version

Creating & Mapping Products and Plans

API Connect v12 modernizes Product and Plan management by moving from v10’s simple, single-file UI to a modular, project-based structure in IBM API Studio. This makes Products and Plans easier to reuse, automate, version, and manage across environments.

v10 (API Designer) :

• Products were created through Add, then New Product.
• One YAML file contained all metadata, included APIs, Plans, visibility, and subscription rules.
• Plans were created inside the Product rather than as separate objects.
• APIs were mapped to Plans using form panels.
• Rate limits and subscription settings were configured inside each Plan.
• Developer Portal visibility was set in the same UI.
• YAML edits were possible in Source mode.

v12 (IBM API Studio) :

• Products and Plans exist as separate, reusable files inside the project.
• They can be shared across multiple APIs or Products.
• Both Form View and Code View are available.
• The modular structure replaces v10’s single YAML file and improves flexibility and consistency.

Step 1 : Create or Open an API Project

• Open IBM API Studio, choose Open Project or New Project, and select a workspace type such as a Git repository, a local folder, or native storage.

Step 2 : Add a New Product Inside the project, select Add Product and provide the Product name, namespace, version, and optional tags.
Step 3 : Create Plans Plans are standalone in v12 and can be linked to multiple Products. Inside the project, select Add Plan and provide the name, namespace, version, and optional tags.

Step 4 : Map APIs, Plans, and Products

• Add APIs to the Product : Open the Product, select Add API, and choose APIs from the project. The Product YAML updates automatically.
• Attach Plans to the Product : In the Product, open the Plans section and select the Plans to associate. Because Plans are standalone, multiple Products can use the same Plan.
• Configure limits inside the Plan : Edit the Plan file to define rate limits, usage rules, and API or operation-level settings. Plans remain independent, so updates do not require editing the Product.

Step 5 : Edit in Form View or Code View

IBM API Studio supports both Form View for configuring metadata, APIs, Plans, visibility, and rules, and Code View for editing the Product and Plan YAML files.

Testing an API

API testing is another area where IBM API Connect v12 introduces a significant shift. While v10 relied heavily on the Test tab in API Designer and the standalone API Connect Tester, v12 moves to a project-based, code-first testing model in IBM API Studio. This allows developers to create, run, and manage tests directly alongside API definitions, integrating testing into modern workflows with version control and automation.

This section compares how API testing was done in v10 vs v12, what changed, what improved, and how users can achieve similar results in v12.

v10 (API Tester) :

• Test tab in API Designer for quick, ad-hoc calls.

• API Tester tool for automated test cases and suites.

• Form-based request creation (method, URL, headers, body).

• Visual policy execution trace for debugging.

• Local Test Environment (LTE) for testing without an external gateway.

• Basic pass/fail validation.

v12 (IBM API Studio) :

• Tests stored inside API projects.
• YAML-based test files (with Form view option).
• Environments defined as separate YAML files with reusable variables.
• Detailed assertions (status, headers, body, schema, logic).
• Tryout feature for quick, interactive testing without writing tests.

Step 1 : Create a Test Open API project → Add a Test. Provide name, namespace, version, tags. Test is created as a YAML file. Optional – Create from Spec: Auto-generates test, assertion, and environment files from an OpenAPI spec.
Step 2 : Configure Test Environment Environments use kind: environment files for clean separation of config. a) Creating an Environment (Form View) From the Quick start page, click Add an environment. Provide the environment name, namespace, version number and tags (optional). Click Create to generate the environment file including variable, secret and value. Add environment variables: including variable, secret and value. The environment configuration updates instantly, making these variables reusable in all tests. Tests automatically substitute ${variableName} during execution.

b) Defining an Environment (Code View – YAML)

You can also create the environment by directly editing YAML in Code view.

An environment uses the structure:

kind: environment
metadata:
  name: Environment_Name
  version: Version
  tags: - Tag1 - Tag2
  namespace: Namespace
spec:
  variables:
  - key: Variable_Key
   value: "${Variable_Name}"
   isSecret: true/false

c) Linking

Assign environments via Form view or reference in test YAML.

Step 3 :  Add Requests and Assertions 

In v12, tests are built from two main components: Requests, which define the API calls, and Assertions, which validate the responses. Assertions are maintained as separate kind: assertion configurations, enabling better modularity, reusability, and governance.

a) Define Requests

• • • Each request specifies how the API should be invoked. You can configure these in Form view or Code view (YAML).
    • A request includes HTTP Method, Endpoint / Path, Headers, Body / Payload and Parameters.
    • Supports multi-request workflows (create → get → update → delete).
    • This enables realistic end-to-end API validation.

b) Add Assertions

Assertions confirm whether the response of each request matches expectations.

Add Assertions (Form View) From the Quick start page, click Add an assertion. Provide assertion name, namespace, version and optional tags. Click Create to generate the assertion file. Add individual validation rules by specifying name, key, action and value which are referenced by test requests during execution.

• • Add Assertions in YAML (Code View)
    • Assertions can also be defined in a separate YAML file using kind: assertion.
    • A test references the assertion file to apply the rules to relevant requests.
    • Assertions can validate status code, headers, JSON files, XML files, plain text body and response time.
    • Supported actions include: equals, lessThan, greaterThan, include, notEquals, etc.

• • • General format:

kind: assertion
metadata:
  name: Assertion_Name
  version: Version
  namespace: Namespace
  tags: - Tag1
spec:
  - name: "Assertion description"
   key: Key_Name
   value: Expected_Value
   action: Comparison_Action

c) Apply Assertions to Requests

• • Each request in the test can reference one or more assertions.
    During execution, IBM API Studio evaluates all validation rules and highlights mismatches.
  • Failure results clearly show the expected vs. actual values.

d) Multi-Request Testing

Tests can include multiple requests, enabling:

• • Authentication → Use token in next request
  • Resource lifecycle testing (Create → Get → Update → Delete)
  • Data-driven sequences using environment variables
  • Cross-endpoint scenario validation

Each request may use different assertion files or share common validation rules.

Step 4 : Run the Test

In v12, authored tests run directly inside IBM API Studio, validating your API against the deployed gateway. Tests only execute if the API is already published to an API Gateway.

a) Execute the Test

• • Open IBM API Studio and select your project.
  • In the Explorer, choose the test file (kind: test).
  • The Run test button becomes active only when:
    • The API is deployed to a gateway
    • The test and its referenced assertions are correctly defined
  • Click Run test to execute the test.
  • IBM API Studio processes the YAML test file, sends each configured request, and applies all referenced assertions.

b) View and Analyze Test Results

After execution, open:

Problems → Test results

The Test results panel shows:

• • Pass/Fail status for each request and assertion
  • Which assertions succeeded or failed
  • Clear indicators of mismatches

Clicking an error opens a detailed Test Results page with three tabs including the test summary, request and response.

You can download your test results in different formats for reference.

TryOut Feature

In v12, IBM API Studio provides an integrated Tryout panel that lets you interactively test API endpoints without writing any test files. This helps you quickly explore how each operation behaves.

How it works :

• • Open API → click Tryout.
  • Fill parameters, body, headers, and auth.
  • Send the request.
  • View status, headers, and response body.

Useful for quick endpoint exploration and debugging.

Publishing an API

In API Connect v10, publishing is done through a Product. An API can be published from the API list or from inside the Editor. To publish, the user must add the API to a new or existing Product, then select a Catalog to publish into.

In API Connect v12, publishing happens at the project level in IBM API Studio. A project or selected assets can be published directly to a Catalog and deployed to one or more gateways after choosing the Catalog and gateways.

Publishing in v10 follows a multi-step structure: select the API, place it in a Product, choose the Catalog, and publish the Product. In v12, the project itself becomes the deployable unit. Products and Plans are no longer mandatory, and users can publish a project directly to a Catalog or deploy it to gateways.

v10 (API Designer) :

• Go to Develop, then APIs, and select the API to publish (from the list or by opening it).
• If multiple provider organizations exist, select the required one.
• If publishing from within the API:
  • Open the API, select the menu, and choose Edit API.
  • Go to Test, then Target Configuration, and turn Auto-publish on if needed.
• Choose how to publish:
  • Create a new Product and enter title and version.
  • Or select an existing Product.
• Select the Catalog and, if enabled, choose the Space in the Catalog.
• If required, select specific gateway services and click Publish.

v12 (IBM API Studio) :

• Open IBM API Studio and select the API project you want to publish.
• Select the project or any file within it (references publish automatically).
• Choose Publish project to a catalog and add an API Manager configuration if required.
• Select the Catalog and the Space if available.
• Choose one or more API Gateways and click Publish.

Governance

Governance in v12 is integrated directly into IBM API Studio, making validation part of the design and testing workflow.

v10 (API Designer) :

• Governance validation in v10 was carried out by running validation scans in API Manager, API Designer, and the toolkit CLI.

• Validation could be triggered from multiple places:

  • Inside an API

  • Inside a Product

  • Governance section in API Manager

  • Catalog or Space

  • Toolkit CLI

• Users selected rulesets and specific rules before running the scan.

• A scorecard displayed validation results, and YAML navigation allowed reviewing issues.

• Results could be downloaded as CSV.

• Published APIs and Products could also be validated directly from the Governance tab within a catalog or space.

v12 (IBM API Studio) :

• Governance is natively integrated into API Studio, part of the core design workflow.

• Rulesets are available through Settings → Ruleset management, automatically synced from API Manager.

• Auto-validation is enabled by default, applying rulesets continuously.

• A Spectral-based engine provides inline feedback directly in the editor.

Step 1: Open Ruleset Management

• From the API Studio home page, click Settings → Ruleset management.

Step 2: View Imported Rulesets

• The Ruleset management tab displays both global rulesets (centrally defined) and custom rulesets (org‑specific).

• These are automatically fetched from API Manager.

Step 3: Configure Auto Validation

• Auto validation is enabled by default for each ruleset.

• You can toggle it off if needed.

Step 4: Validate APIs in the Editor

• Linting is built-in and automatic, with the integrated engine applying the selected rulesets directly during API design and testing.

• Validation runs seamlessly in the editor, highlighting issues inline for immediate correction.

Conclusion

Migrating from API Connect v10 to v12 is more than a version upgrade it introduces a modernized approach to API development. IBM has moved from a visual, form-driven model to a project-centric, code-first framework that strengthens modularity, reusability, and lifecycle management.

For teams familiar with v10, the transition may feel different from the simplicity of API Designer, but v12’s IBM API Studio provides greater scalability, governance, and alignment with industry standards such as OpenAPI. By separating metadata from specifications, introducing reusable Products and Plans, and embedding structured testing directly into projects, v12 enables developers to create APIs that are easier to maintain, version, and automate.

The key benefit is that v12 unifies the API lifecycle into a single, consistent workspace. Whether designing, applying policies, mapping Products and Plans, testing, or publishing, each step now fits into a coherent project structure that supports collaboration and version control.

By adopting these changes, API teams can replicate familiar v10 workflows while gaining improved clarity, stronger lifecycle control, and new efficiencies that support modern API practices.