Quick answer: A data bucket is a shared piece of state that multiple Mockoon routes can read and update, which lets you model a create-then-read flow without a real backend. It is a convenient way to build stateful behavior in a GUI tool, but the state lives in a client-specific configuration. A spec-based approach derives stateful behavior from the OpenAPI contract and keeps the behavior portable across tools. Use buckets for fast local stateful mocks; prefer contract-based state when the behavior must run in CI and be shared by the team.
What a data bucket gives you
Without shared state, each route returns a fixed response and a POST cannot influence what a later GET returns. A data bucket acts as a small in-memory store that routes can reference through templating, so a write can append to it and a read can echo it. This is the lightweight version of a database for a mock.
| Capability | Data buckets | Spec-based state |
|---|---|---|
| Shared state across routes | Yes, via a bucket | Derived from the contract |
| Create then read flows | Supported through templating | Modeled as stateful operations |
| Where logic lives | GUI configuration and templates | OpenAPI plus a mock engine |
| Portability | Tied to the tool | Runs on any compatible engine |
| Reset behavior | Configured per environment | Defined alongside the contract |
Wiring a route to a bucket
You define a bucket with an initial value, then reference it in responses and update it from writes. The exact syntax uses the tool's templating, but the intent is a shared array that POST appends to and GET returns.
After a client posts an item, the GET reflects it, which is enough to develop a front-end against a stateful flow before the real API exists.
The limits of GUI-held state
Because the state rules live in a tool-specific configuration, they do not travel with the OpenAPI contract. A mock engine in CI, a generated server, or another tool cannot read the bucket template. The behavior can also drift from the real contract because the bucket's shape is hand-written rather than validated against the schema. When the API changes, the bucket can quietly keep returning an outdated shape while the UI still appears to work.
Spec-based state as the portable alternative
A contract-driven mock uses the operation definitions to decide how a write changes state and what a read returns, so the behavior is generated from the same schema the real API follows. The state may still be in memory, but its shape is validated against the contract and the mock runs in CI without a GUI.
The mock engine understands that a POST creates a resource matching NewItem and that the GET array should include it, so you do not hand-wire the relationship.
Resetting and isolating state
Stateful mocks only stay reliable if the state resets between tests. A bucket that persists across runs creates order-dependent failures where one test sees another test's data. Whether you use buckets or a spec engine, define how state is reset at the start of each run and keep the mock isolated from shared environments. The advantage of spec-based state is that the reset and the shape are declared in one place that CI can execute consistently.
How an AI agent approaches the choice
An agent can quickly hand-wire a bucket for a prototype, which is fine for a short-lived local demo. If the mock is meant to survive and run in CI, ask the agent to generate the stateful behavior from the OpenAPI operations instead, and add tests that perform a POST followed by a GET. Verify the response validates against the schema so the mock does not drift from the real API. Use buckets as a rapid starting point, then move the durable behavior into the contract.
Concurrency and multiple clients
When several front-end clients write to the same bucket at once, the order of updates is nondeterministic, and a simple append can lose or interleave data. That is acceptable for a local prototype but worth remembering before you treat the mock as evidence of real concurrent behavior. A real database serializes transactions and enforces constraints; an in-memory bucket does not, so keep concurrency testing against the contract-driven mock or the real service rather than drawing conclusions from the GUI bucket.
Frequently asked questions
Are data buckets only for GUI use?
They are defined in the tool's configuration and can run through its CLI, but the logic is specific to that tool and not portable to other mock engines. Spec-based state is the portable option.
Can a data bucket model a database?
It can model simple shared state for create-and-read flows, but it is not a real database and should not be used for complex queries or persistence. It is a development aid.
How do I prevent tests from sharing bucket data?
Reset the bucket at the start of each test run and keep the mock isolated. Order-dependent failures are usually a sign that state was not reset between runs.
Why validate the bucket against the OpenAPI schema?
Hand-written responses can drift from the real contract, and the UI then builds against a shape the API does not return. Schema validation catches that drift before it becomes a runtime bug.
This is part of the Powerduck vs Mockoon: OpenAPI Mock Servers — start there for the full comparison of GUI mocks and spec-driven state.
Top comments (0)