Detect and Heal Change

The change-response workflow has two complementary phases:

  • Phase 1 - Heal API Definition: When a new spec version arrives, use api_refactor_analyze to identify operation mappings, additions, deletions, and parameter changes, then use api_operation_apply to apply agent-confirmed mutations to the API definition and update the definition URL.

  • Phase 2 - Heal Test Cases: Once the definition is synced, use analyze_api_impact to identify which existing tests are broken by the changes, then use rest_test_step_update to fix impacted steps.

Run both phases together for a complete healing cycle - API definition synced, tests fixed, and project saved. Four-staged canned prompts wrap the underlying tools into a guided, checkpointed flow - see Staged canned prompts below.

Heal API Definition

API refactor analysis

api_refactor_analyze READ

Analyzes API definition changes between the current spec stored in ReadyAPI and a new spec version. Wraps ReadyAPI refactoring logic to identify operation mappings with confidence scores, parameter additions, removals, and modifications, unmatched old operations with recommendations, and net-new operations.

Key parameters:

  • project*, apiName*, newSpec*, newSpecSourceType* (URL | FILE | CONTENT)

Try asking your AI client: "Analyze spec changes, propose operation mappings and changes."

API operation application

api_operation_apply WRITE

Applies agent-confirmed changes to an API definition. Mutates operations (create, update, or delete) based on agent decisions and updates the project's definition URL to point to the new spec. Supports rollback through an optional backup copy. Returns a full summary of applied and failed changes, warnings, and definition URL update status.

Key parameters:

  • project*, apiName*, newSpecSourceType*, newSpec*, agentConfirmations*; optional: createDefaultRequests (default: true), createBackupCopy (default: true)

Try asking your AI client: "Apply the confirmed changes to the Order Service API and update the definition URL."

Heal Test Cases

Analyze API impact

analyze_api_impact READ

Diffs a new spec against the existing one stored in ReadyAPI using openapi-diff-core. Matches changed endpoints to test suites and returns the full spec diff, a list of impacted test steps, and per-step healing advice.

Key parameters:

Try asking your AI client: "Compare this new spec to what's in ReadyAPI and tell me which tests it breaks."

Supported newSpecSourceType values

newSpecSourceType accepts the following values for analyze_api_impact:

Table 86. Supported values

Value

Description

URL

Remote URL pointing to a Swagger or OpenAPI definition.

FILE_PATH

Absolute path to a local OpenAPI/Swagger file (JSON or YAML).

RAW_STRING

Inline JSON or YAML spec content provided directly in the prompt.



REST Test Step update

rest_test_step_update WRITE

Applies LLM-recommended parameter, request body, response, and assertion changes to a single named test step. Call once per impacted step. Returns applied and skipped changes with reasons, and whether the project was saved.

Key parameters:

  • projecttestSuite*, testCase*, testStep*; optional: parameterChanges[], requestBodyChanges[], responseChanges[], assertionChanges[]

Try asking your AI client: "Apply the recommended fixes to the impacted tests."

Input Schema

Defines the changes to apply to a single test step. Pass the values returned by analyze_api_impact directly; do not construct them manually.

Table 87. Input schema

Parameter

Type

Required

Description

project

string

Yes

Project name

testSuite

string

Yes

Exact suite name from analyze_api_impact output

testCase

string

Yes

Exact case name

testStep

string

Yes

Exact step name

parameterChanges[].changeType

ADDED | REMOVED | MODIFIED

No

Type of parameter change

parameterChanges[].name

string

No

Parameter name

parameterChanges[].location

query | header | path | matrix | plain

No

Parameter location

parameterChanges[].oldType

string

No

Previous parameter type

parameterChanges[].newType

string

No

Updated parameter type

parameterChanges[].newRequired

boolean

No

Updated required flag

requestBodyChanges[].changeType

ADDED | REMOVED | MODIFIED

No

ADDED inserts a typed placeholder; REMOVED deletes the field; MODIFIED resets it

requestBodyChanges[].fieldPath

string

No

Slash-separated field path, for example, /address/city

requestBodyChanges[].newType

string

No

Updated field type

responseChanges[]

-

No

Acknowledged and listed as skipped - response bodies are re-validated by the step's schema-compliance assertion after the spec update

assertionChanges[].assertionType

string

No

Assertion type, for example, ValidHttpStatusCodes

assertionChanges[].healingAction

ADD_STATUS_CODE | REMOVE_STATUS_CODE | ADD_JSONPATH_EXISTENCE | REMOVE_JSONPATH_EXISTENCE | REMOVE_JSONPATH_CONTENT | MANUAL_REVIEW

No

Action to apply. MANUAL_REVIEW is always skipped and returned for human attention.

assertionChanges[].statusCode

string

No

Required for ADD_STATUS_CODE and REMOVE_STATUS_CODE

assertionChanges[].fieldPath

string

No

Required for JSONPath actions

assertionChanges[].assertionName

string

No

Required for REMOVE_JSONPATH_CONTENT and MANUAL_REVIEW



Output schema

Returned after processing the Input Schema above. Use applied[] and skipped[] to verify what changed. For any entry in skipped[] with healingAction: MANUAL_REVIEW, intervention in ReadyAPI is required before re-running.

Table 88. Output schema

Field

Type

Description

project

string

Project name

testSuite

string

Suite name

testCase

string

Case name

testStep

string

Step name

applied[]

array

Changes applied, each with changeType, name, and detail

skipped[]

array

Changes skipped, each with changeType, name, and reason

saved

boolean

Whether the project was saved after applying the changes



See Also

Publication date: