Skip to main content

Key Concepts

Understanding these core concepts will help you get the most out of SureStage.

Simulations​

A simulation is an isolated Sandbox that hosts a set of mock API endpoints. Each simulation:

  • Has a unique URL for receiving requests
  • Contains its own set of routes, responses, and state
  • Can be started, stopped, and reset independently
  • Supports multi-protocol configurations

Think of a simulation as a lightweight, disposable API server.

Routes​

A route defines an endpoint pattern that your simulation responds to. Routes are defined by:

  • HTTP Method - GET, POST, PUT, PATCH, DELETE, etc.
  • Path - URL pattern with optional parameters (e.g., /users/:id)
  • Responses - One or more response configurations

Path Parameters​

Routes support dynamic path segments using the :param syntax:

GET /users/:userId/orders/:orderId

Responses​

Each route can have multiple responses configured. Responses include:

  • Status code - HTTP status (200, 404, 500, etc.)
  • Headers - Custom response headers
  • Body - JSON, XML, or any content type
  • Delay - Simulated latency in milliseconds
  • Priority / Weight - For controlling which response is returned

Response Selection​

When a request matches a route, SureStage selects a response based on:

  1. Rules - Conditional matching on headers, query params, or body content
  2. Sequence - Return responses in order (useful for testing retries)
  3. Random - Weighted random selection
  4. Default - Fallback response when no rules match

State​

SureStage supports stateful mocking where API behavior changes based on previous interactions:

  • Track entity state across requests (e.g., create then retrieve)
  • Simulate workflows (e.g., order placed -> payment processed -> shipped)
  • Reset state on demand for reproducible testing

Environments​

An environment is a reusable group of routes and responses that can be:

  • Shared across simulations
  • Versioned and published
  • Imported from the SureStage library

Blueprints​

A blueprint is a reusable simulation template that captures a full configuration:

  • Create blueprints from existing simulations
  • Publish to your organization's library
  • Fork or adopt blueprints shared by your team
  • Version blueprints to track changes over time

Flows​

A flow is an automated sequence of API calls used for testing:

  • Chain multiple requests with variable passing
  • Add assertions on response status, headers, and body
  • Include conditional logic and loops
  • Run flows on a schedule or via CI/CD

Proxy Modes​

SureStage can act as a proxy to real APIs:

ModeDescription
ProxyForward all requests to the target API
RecordForward requests and record the response pairs
ReplayReturn recorded responses without hitting the target
HybridUse recorded responses when available, proxy otherwise

Organizations & Multi-Tenancy​

SureStage supports team collaboration with:

  • Organizations - Top-level container for team resources
  • Workspaces - Subdivision within an organization for project isolation
  • Roles - Administrator, Manager, Member, Viewer with granular permissions
  • SSO/SCIM - Enterprise identity provider integration