Editing an API Definition

Editing an API Definition allows you to refine, extend, or correct an existing request without breaking the overall workflow. Changes take effect immediately and apply to all future executions that rely on this definition.

Why it matters

• Continuous improvement: APIs evolve, and definitions must evolve with them.
• Safe updates: You can adjust parameters, body structure, or metadata without recreating the API.
• Operational clarity: Teams can quickly see what changed and adapt their tests accordingly.

When to use it

• The endpoint path, method, or version has changed.
• New parameters were added, or existing ones became optional/required.
• You need to update the authentication details or the timeout behavior.
• You want to test variations of the API without creating duplicates.

Core concepts

• Editable Definition – an existing API that can be updated in place.
• Credential Override (Test Only) – temporary values used only during testing.
• Inline Testing – running the API directly from the edit page.

How it works

1. You open an existing API Definition from the list.
2. You update any of the editable fields (core info, parameters, body mode).
3. Optional test values can override defaults for a single execution.
4. Once saved, the updated definition becomes the new reference for the project.

How to use it

Step 1: Open an existing API Definition

From API Manager → View all, select an API and open it in Edit mode.

Step 2: Update core fields

You may update:

• Name and Description
• Endpoint and Method
• Version label
• Timeout value

Step 3: Modify authentication (if needed)

• Change the authentication type if the API contract has changed.
• Authentication fields are shown dynamically based on the selected type.

Step 4: Adjust Body Mode

• Switch between Parameters and Raw JSON if the request structure changes.
• When switching to Raw JSON, Body parameters are disabled automatically.
• When switching back to Parameters, Body parameters become available again.

Step 5: Edit parameters

You can:

• Add new parameters
• Update name, type, location, or description
• Mark parameters as required or optional
• Remove parameters that are no longer used

Step 6: Run an inline test

Use Test This API on the edit page:

• Enter temporary values for parameters.
• Optionally override authentication values for this test only.
• Click Run Test to view the response immediately.

Step 7: Save changes

Click Update API to apply all changes. The updated definition is now used by all related tests.

Best practices

• Keep edits focused and intentional—avoid unrelated changes in one update.
• Retest the API after any structural change (endpoint, body mode, parameters).
• Use clear descriptions when modifying behavior so teammates understand the intent.

Common mistakes

❌ Mistake 1: Switching to Raw JSON but leaving old Body parameters untouched
✔ Fix: Remove unused Body parameters or switch back to Parameters mode if needed.

❌ Mistake 2: Overwriting credentials unintentionally during testing
✔ Fix: Only enter credential values when you intend to override them for the test.

Security & permissions

• Only users with appropriate project access can edit API Definitions.
• Saved authentication data remains protected and is not exposed in responses.
• Test-only overrides are not persisted unless explicitly saved.

Related documentation

• Creating a New API Definition
• Testing an API
• API Parameters
• Using API Definitions in Test Cases