How Sandboxing Works
Playground API combines an immutable global seed catalog with high-performance Copy-on-Write (CoW) session overlays. Discover how thousands of concurrent developers mutate endpoints independently without collisions or database maintenance.
The 3-Layer Copy-on-Write (CoW) Architecture
Every read request dynamically executes a three-stage pipeline to construct your realistic view of the world:
Immutable Baseline Seed
Global seed dataset (100 posts, 10 users, 500 comments) acts as read-only blueprint.
Visitor Mutation Overlay
All POST, PUT, and DELETE operations are stored in private diffs keyed by session identity.
In-Memory Query Resolver
Merges Layer 1 + Layer 2 in memory in <1ms with conflict resolution and tombstones.
Immutable Baseline Seed
Global seed database containing 100 posts, 10 users, 500 comments, and 200 todos. It serves as the baseline blueprint and is never modified by any visitor.
Visitor Mutation Delta
When you call POST, PUT, or DELETE, your changes are stored in a private diff dictionary keyed by your unique session identity hash.
Virtual Query Resolver
When querying GET /posts, the resolver merges Layer 1 + Layer 2 in memory. Deleted items are filtered out, updated records are patched, and newly created items are prepended in <1ms.
What Happens When You Mutate
Here are the concrete behavioral guarantees provided by your sandbox overlay:
Newly created items are assigned an auto-incremented ID and saved to your private delta overlay. They immediately appear in subsequent GET /posts queries and increase total pagination counts.
Modifying an existing seed item (e.g. changing title on post #1) stores only your field patch in your overlay. The baseline record remains untouched for everyone else in the world.
Deleting an item masks its ID in your visitor overlay. Subsequent collection queries filter it out, and single-item requests to GET /posts/:id return a realistic 404 Not Found.
Filters (?userId=1), full-text search (?q=keyword), and sorting (?_sort=id&_order=desc) execute on the merged dataset seamlessly.
Visitor Identity Resolution
How does the server route mutations to your private overlay? The API inspects incoming requests using a deterministic waterfall:
For web browsers, an HMAC-signed pg_identity cookie is automatically assigned on the first HTTP handshake with credentials: 'include'.
Pass an X-Playground-Identity header to isolate parallel test runners or mobile apps without cookies.
Attaching Authorization: Bearer <token> routes requests to the authenticated user account sandbox with role-based permissions.
Sandbox Lifecycle & Data Retention
10-Day Sliding Inactivity Window
Visitor sandboxes are kept alive as long as they receive requests. If a sandbox remains untouched for 10 consecutive days, the overlay is automatically recycled to keep the cluster pristine.
Instant Atomic Reset
Whenever you want to restart your application state from zero, make a DELETE /session/reset call. The server discards the session delta in microseconds.
Want to inspect your current session state?
Check your current memory quota, active mutations count, and session age in the Sandbox Dashboard.