Skip to main content

Response Versioning

Track, compare, and manage versions of your mock API responses with draft workflows, rollback capability, and response pinning. This feature helps teams collaborate on response definitions and maintain a complete audit trail of changes.

Prerequisites​

  • An existing mock simulation with at least one route and response
  • Basic understanding of simulation responses

Understanding Response Versions​

Every time you modify a response body, headers, or status code, SureStage automatically creates a version record. This allows you to:

  • View the complete history of response changes
  • Compare any two versions to see what changed
  • Revert to previous versions without manual reconstruction
  • Pin responses to prevent accidental modifications
  • Create draft versions for testing changes before publishing

Creating Drafts​

Drafts are working copies of responses that can be edited before promoting to live.

Create a Draft from Current Response​

  1. Navigate to a response in your simulation
  2. Click Create Draft or + Draft
  3. Optionally name the draft (e.g., "Experiment with new payload shape")
  4. Click Create

You now have a draft version that's independent from the live response.

Viewing Drafts​

  1. Open the response
  2. Click the Drafts tab
  3. See all draft versions with creation timestamps and creator names

Each draft shows:

  • Draft name/label
  • Creator name
  • Created timestamp
  • Status (active, finalized)

Editing a Draft​

  1. Select a draft from the drafts list
  2. Click Edit
  3. Modify the response:
    • Status code
    • Headers (JSON)
    • Body (JSON/raw)
  4. Click Save to update the draft

Changes to drafts don't affect the live response until you promote.

Promoting a Draft to Live​

When you're satisfied with a draft, promote it to become the live response:

  1. Open the draft
  2. Click Promote
  3. Confirm the action
  4. The draft content becomes the live response
  5. A new version record is created with source "draft_promote"

Discarding a Draft​

If you no longer need a draft:

  1. Select the draft
  2. Click Discard (⚠️ cannot be undone)
  3. Confirm deletion

Viewing Version History​

List Response Versions​

  1. Open a response in your simulation
  2. Click the Versions or History tab
  3. View paginated list of all published versions (excludes drafts)

Each version shows:

  • Version ID (UUID)
  • Creation timestamp
  • Creator name
  • Source (e.g., "direct_edit", "draft_promote", "rollback")
  • Status code, headers, and body summary

Get Version Details​

  1. Click on a version in the history
  2. View the complete response definition:
    • Full status code
    • Complete headers object
    • Full response body
    • Creation timestamp
    • Creator information

Comparing Versions (Diff)​

Compare Two Versions​

  1. Navigate to the response version history
  2. Click Compare or select two versions
  3. Enter the older version UUID as "from"
  4. Enter the newer version UUID as "to"
  5. View the structured diff

The diff shows:

  • Added: Fields present in newer version
  • Removed: Fields present in older version
  • Modified: Fields that changed between versions
  • Unchanged: Fields that remain the same

Example Diff​

{
  "statusCode": {
    "from": 200,
    "to": 201,
    "status": "modified"
  },
  "headers": {
    "X-Custom-Header": {
      "status": "added"
    },
    "Content-Type": {
      "from": "application/json",
      "to": "application/json; charset=utf-8",
      "status": "modified"
    }
  },
  "body": {
    "userId": {
      "status": "added"
    },
    "message": {
      "status": "removed"
    }
  }
}

Rolling Back to Previous Versions​

Rollback Workflow​

  1. Open the response history
  2. Find the version you want to restore
  3. Click Rollback to this version
  4. Confirm the action
  5. The response is restored to that version's state
  6. A new version is created with source "rollback"

Example: If you accidentally changed a response, you can rollback to restore the previous working version.

Rollback Behavior​

  • Only the response content is restored (status code, headers, body)
  • The rollback creates a new version record for audit trail
  • Previous versions remain in history
  • The live response is immediately updated

Pinning Responses​

Pin responses to prevent accidental edits in high-risk scenarios.

Pin a Response​

  1. Open the response
  2. Click Pin or Lock
  3. Optionally enter a reason (e.g., "Locked for QA certification")
  4. Click Confirm Pin

Pin Restrictions​

When a response is pinned:

  • Cannot edit the response body, headers, or status code
  • Cannot delete the response
  • Can still view history and create drafts
  • Can still create snapshots
  • Admin can override the pin if needed

Unpin a Response​

  1. Open the pinned response
  2. Click Unpin or Unlock
  3. Confirm the action

The response is now editable again.

Simulation-Level Version History​

View all version changes across every response in a simulation.

Access Simulation Version Timeline​

  1. Open a simulation
  2. Click History or Version Timeline
  3. View paginated timeline of all response changes for the simulation

This shows:

  • Which response was modified
  • The user who made the change
  • The timestamp
  • Whether it was a direct edit, draft promotion, or rollback
  • Quick link to view the version
  • Filter by user
  • Filter by response
  • Search by date range
  • Sort by newest/oldest first

Common Workflows​

A/B Testing Response Variants​

  1. Create Draft A with variant 1
  2. Create Draft B with variant 2
  3. Test both drafts in different environments
  4. Promote the winning variant
  5. Keep the rollback history for documentation

Collaborative Editing​

  1. Team member creates a draft with proposed changes
  2. Another team member reviews the draft
  3. Use diff to see exactly what changed
  4. If approved, promote the draft
  5. If rejected, discard the draft

Emergency Rollback​

If a response change breaks tests:

  1. Navigate to response history
  2. Find the last known-good version
  3. Click Rollback
  4. Confirm
  5. The response is immediately restored
  6. The broken version remains in history for analysis

Documentation Trail​

Use response versioning as documentation:

  1. Each version captures the exact response at a point in time
  2. Diffs show what evolved and why
  3. Creator info tracks who made each change
  4. Sources (direct_edit, draft_promote, rollback) show the action type

Version History Limits​

Retention Policy​

  • Versions are retained indefinitely
  • All drafts are retained until explicitly discarded
  • Pinned responses cannot be deleted or modified
  • Consider archiving old responses periodically to manage volume

Performance​

  • List endpoints support pagination (default 20 items/page)
  • Diff operations work with any two versions
  • Simulation-level history is paginated for large simulations

Troubleshooting​

Can't Find an Old Version​

  • Check the version history pagination
  • Use simulation-level timeline to find the response
  • Versions are never deleted; search by date range
  • Contact your workspace admin for very old versions

Rollback Didn't Work​

  • Verify you selected the correct target version
  • Check that the response permissions allow rollback
  • Ensure the response hasn't been pinned
  • Review the operation result in the activity log

Comparison Shows No Differences​

  • Verify you selected different version UUIDs
  • Check that one version is actually newer than the other
  • Both versions may be identical (no changes occurred)

Can't Edit Because Response Is Pinned​

  • Unpin the response first (or ask admin)
  • Create a draft instead (drafts bypass the pin)
  • Promote the draft when ready
  • This is intentional to prevent accidental modifications

API Reference​

Version Management Endpoints​

MethodPathDescription
GET/responses/:id/versionsList response versions
GET/responses/:id/versions/:versionIdGet version details
GET/responses/:id/versions/diffDiff two versions
POST/responses/:id/rollbackRollback to version

Draft Endpoints​

MethodPathDescription
POST/responses/:id/draftsCreate draft
GET/responses/:id/draftsList drafts
PATCH/responses/:id/drafts/:draftIdUpdate draft
POST/responses/:id/drafts/:draftId/promotePromote draft
DELETE/responses/:id/drafts/:draftIdDiscard draft

Pinning Endpoints​

MethodPathDescription
POST/responses/:id/pinPin response
DELETE/responses/:id/pinUnpin response

Next Steps​