Stateful Mocks

Stateful mocks let you test scenarios that require data persistence. Two main features:

• Data Buckets - In-memory JSON arrays that persist across requests
• Sequence Responses - Return different responses based on request count

Create a REST API with persistence in 3 steps:

1. Create a Bucket

Go to Data tab → New Bucket → name it users

[
  { "id": "1", "name": "Alice" },
  { "id": "2", "name": "Bob" }
]

2. Create Endpoints

Create endpoints and link them to the bucket:

For each endpoint: enable Stateful toggle → select bucket → ID field auto-fills from path param.

3. Test It

# List users
curl -H "X-API-Key: YOUR_KEY" https://api.mockspec.dev/mock/users

# Create user
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -d '{"name": "Charlie"}' \
  https://api.mockspec.dev/mock/users

# List again - Charlie is there
curl -H "X-API-Key: YOUR_KEY" https://api.mockspec.dev/mock/users

The endpoint's method and path determine the operation:

• GET without ID param → returns all items
• GET with ID param → returns single item (404 if not found)
• POST → creates item, auto-generates UUID if no ID in body
• PUT with ID param → replaces item
• DELETE with ID param → removes item

All endpoints linked to the same bucket share data. Changes are visible immediately.

For non-stateful endpoints, access bucket data in response templates:

{
  "users": {{ bucket 'users' }},
  "count": {{ bucketLength 'users' }}
}

Return different responses based on request count. Set Sequence Position on a variant.

Example: Test Retry Logic

Create endpoint with three variants:

First two requests fail, third succeeds. Perfect for testing retry logic.

Clear sequence counters and reset buckets to initial data:

• UI: Settings tab → Reset State
• API: POST /projects/:id/state/reset

State is in-memory and resets on server restart.