Mock Snapshots

Capture and share point-in-time snapshots of your mock simulation state, including request/response pairs, route configuration, and mock state data. Snapshots enable knowledge sharing, scenario reproduction, and collaboration across teams.

Prerequisites

• An existing mock simulation with routes and responses
• At least one completed request/response interaction
• Basic understanding of simulation structure

Understanding Snapshots

Snapshots capture:

• Request data - Method, path, headers, query parameters, body
• Response data - Status code, headers, response body
• Route configuration - Route settings at time of snapshot
• Simulation configuration - Simulation settings at time of snapshot
• Mock state - Variables, environments at time of snapshot (optional)

Snapshots are immutable point-in-time records useful for:

• Documenting API behaviors and edge cases
• Sharing examples with team members
• Testing client implementations
• Regression testing
• Knowledge base building

Taking a Snapshot

Snapshot from Request Log

Capture an actual request/response from your simulation traffic:

1. Open simulation Request Log or Live Traffic
2. Find a request/response pair you want to snapshot
3. Click Create Snapshot or Save as Snapshot
4. Fill in snapshot details:

{
  "instanceId": "550e8400-e29b-41d4-a716-446655440000",
  "routeId": "660e8400-e29b-41d4-a716-446655440000",
  "requestData": {
    "method": "POST",
    "path": "/api/users",
    "headers": { "Content-Type": "application/json" },
    "body": { "name": "John Doe", "email": "john@example.com" }
  },
  "responseData": {
    "statusCode": 201,
    "headers": { "Content-Type": "application/json" },
    "body": { "id": "user-123", "name": "John Doe", "email": "john@example.com" }
  },
  "title": "Create User - Success",
  "description": "Successful user creation with all required fields",
  "tags": ["happy-path", "user-api", "onboarding"],
  "visibility": "workspace"
}

Manual Snapshot Creation

Create a snapshot without live traffic:

1. Open the simulation
2. Click Create Snapshot (in the Snapshots section)
3. Manually enter request/response data:
   • Method and path
   • Headers and body
   • Expected response status and body
   • Route configuration
4. Click Create

Snapshot Metadata

Fill in these optional details:

• Title - Short name (e.g., "Create User - Success")
• Description - What this snapshot demonstrates
• Tags - Categories (e.g., "happy-path", "error-case", "edge-case")
• Visibility - Who can access it:
  • private - Only you
  • workspace - Your company/workspace
  • public - Anyone with the short ID
• Expiration - Optional ISO 8601 date when snapshot expires

Managing Snapshots

List Your Snapshots

1. Open simulation or dashboard
2. Click Snapshots or My Snapshots
3. View your created snapshots with:
   • Title and description
   • Creation timestamp
   • Creator name
   • Visibility level
   • Access count

List Simulation Snapshots

View all snapshots for a specific simulation:

1. Open the simulation
2. Click Snapshots tab
3. See all snapshots for that simulation
4. Filter by visibility or search by title

Find a Snapshot

Search snapshots by:

• Title or description
• Tags
• Creator name
• Simulation
• Date range

Sharing Snapshots

Get Snapshot Short ID

Each snapshot has a unique short ID (e.g., sn_abc123xyz):

https://surestage.io/snapshots/sn_abc123xyz

Share with Team

1. Open snapshot
2. Click Share
3. Copy the snapshot URL
4. Send to team members
5. They can access based on visibility setting:
   • Private: Only creator can access
   • Workspace: Company members can access
   • Public: Anyone with URL can access (no auth required)

Set Visibility Level

Change who can access a snapshot:

1. Open snapshot
2. Click Edit or gear icon
3. Change Visibility:
   • private - Only you
   • workspace - Your company
   • public - Anyone
4. Save

Make Snapshot Public

Share a snapshot with external partners:

1. Open snapshot
2. Set visibility to public
3. Copy short URL or QR code
4. External users can view without logging in
5. They see request/response data but cannot modify

Editing Snapshot Metadata

Update snapshot information (request/response data is immutable):

1. Open snapshot
2. Click Edit
3. Update:
   • Title
   • Description
   • Tags
   • Visibility
   • Expiration date
4. Click Save

What Cannot Be Changed

Once created, these snapshot elements are immutable:

• Request data (method, path, headers, body)
• Response data (status, headers, body)
• Route configuration snapshot
• Simulation configuration snapshot
• Creation timestamp
• Creator information

This immutability ensures snapshots are reliable historical references.

Using Snapshots

View Snapshot Details

1. Open a snapshot
2. See organized view of:
   • Request - Method, path, headers, body
   • Response - Status, headers, body
   • Route Config - Route settings at snapshot time
   • Simulation Config - Simulation settings at snapshot time
   • Metadata - Title, tags, visibility, timestamps

Copy Request

Copy snapshot request to test in your client:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'

Test Against Mock Simulation

1. Open snapshot
2. Click Test Against Mock
3. Choose target simulation
4. Mock processes the request and shows result
5. Compare with snapshot response

Snapshot Replay (Future)

Create a temporary replay simulation from snapshot:

1. Open snapshot
2. Click Create Replay Simulation
3. Temporary mock simulation is created with snapshot data
4. Test your client against it
5. Click Destroy Replay when done

(Currently in development - check availability in your version)

Snapshot Use Cases

Documentation

Build knowledge base of API behaviors:

1. Create snapshots for common scenarios
2. Tag them (e.g., "success", "validation-error", "timeout")
3. Share with new team members
4. Link from API documentation

Example snapshots:

• Happy path workflows
• Error scenarios (4xx, 5xx)
• Edge cases (empty arrays, null values)
• Rate limit responses

Testing & QA

Standardize test scenarios:

1. Create snapshots for each test case
2. QA uses snapshots as test data
3. Ensure consistent test execution
4. Track changes to expected responses

Onboarding

Accelerate developer onboarding:

1. Create snapshots of core API flows
2. New developers review snapshots
3. Test their client code against snapshots
4. Tag by complexity level

Client Development

Share API contract with consumers:

1. Document API using snapshots
2. Share public snapshots
3. Consumers implement clients
4. Reduce integration issues

Snapshot Expiration

Set snapshots to automatically expire:

1. Open snapshot
2. Click Edit
3. Set Expires At to future ISO 8601 date
4. Save

Once expired:

• Snapshot becomes inaccessible
• Returns 404 or "expired" message
• Data is retained but hidden
• Can be manually re-activated by creator

Common Workflows

Create Snapshot Documentation Set

1. Create snapshots for all main API flows
2. Tag with flow names (e.g., "user-signup", "checkout")
3. Set to workspace visibility
4. Share documentation link in team wiki
5. Reference snapshots in markdown docs

Regression Testing

1. Create snapshot for each bug found
2. Tag with bug ID
3. Verify fix by testing snapshot request
4. Keep snapshots as regression test references
5. Run periodic checks against snapshot baselines

Cross-Team Handoff

1. Create snapshots of completed work
2. Set to public for external teams
3. Send snapshots to partner team
4. They implement clients based on snapshots
5. Later compare live API against snapshots

Troubleshooting

Snapshot Not Accessible

• Check visibility setting (private snapshots need creator access)
• Verify workspace membership for workspace visibility
• Check if snapshot has expired
• Ensure short ID is correct

Can't Create Snapshot

• Verify simulation has at least one route
• Check that you have permission to snapshot the simulation
• Ensure request/response data is complete
• Try from request log instead of manual creation

Snapshot Shows Old Data

• Snapshots are immutable - they show data at creation time
• If route changed after snapshot, snapshot still shows old config
• This is intentional for historical accuracy
• Create a new snapshot to capture current state

Need to Share Private Snapshot

• Open snapshot and change visibility to workspace or public
• Create a new public snapshot with the same data
• Ask creator to change visibility (if you don't have permission)

API Reference

Snapshot Management Endpoints

Method	Path	Description
POST	/snapshots	Create snapshot
GET	/snapshots	List your snapshots
GET	/snapshots/instance/:id	List simulation snapshots
GET	/snapshots/:shortId	Get snapshot details
PATCH	/snapshots/:shortId	Update snapshot metadata
DELETE	/snapshots/:shortId	Delete snapshot

Future Endpoints

Method	Path	Description
POST	/snapshots/:shortId/replay	Create replay simulation
DELETE	/snapshots/:shortId/replay	Destroy replay simulation

Next Steps

• Routes and Responses - Learn about route configuration
• LLM Mocking - Share LLM mock scenarios
• Analytics - Track snapshot usage and insights
• Environments - Reuse configurations across snapshots