Skip to main content

Stateful Mocks

When creating a mock API that mimics the behavior of a real-world API, simulating real-time behavior is essential. Often, this involves persisting state between two or more independent API calls. For instance, if a customer-ID is sent in one API request, it might need to be used in subsequent requests, even though it is not explicitly included in them. To address such scenarios, Beeceptor provides stateful mocks, which enable you to maintain and manage state across API calls.

Stateful mocks are especially useful for simulating workflows or operations that require data persistence, sequential logic, or dynamic responses based on previous requests. Beeceptor offers three types of stateful helpers to achieve this:

  • Step Counter - A whole number that can be incremented, decremented, or reset.
  • Data Store - A named key-value store that supports numbers, strings, and objects.
  • List - A collection of values (numbers, strings, etc.) where duplicates are allowed. The values are retrieved in LIFO order.

Step Counter​

The Step Counter is a numerical helper designed to maintain sequences across requests. You can use it to simulate incremental IDs, count the number of API calls, or track steps in multi-stage processes.

Syntax​

{{ step-counter 'operation' 'counterName' value }}

Operation:

  • Increment (inc): Increments the counter by a given value (default is 1). This operation accepts both positive and negative values. If the specified counter (counterName) does not already exist, it will be created and initialized with the provided value.
  • Retrieve (get): Retrieves the current value of the specified counter.
  • Set to specific value (set): Updates counter to exact value
  • Reset (reset): Resets the counter to a specified value, overwriting its current state. If no value is provided, the counter is reset to 0 by default.

Counter Name:

  • The counter name must be a string.
  • It should be alphanumeric but can also include spaces, :, -, and _. No other special characters are allowed.
  • The maximum length of the counter name is limited to 50 characters.
  • It is case-sensitive, meaning Counter1 and counter1 would be treated as different counters.

Example​

In the following example, unique order IDs are generated for an e-commerce system, where each new order is assigned a sequential order number. This template first performs an increment action to update the counter, and then retrieves the updated value to populate the JSON field.

{{step-counter 'inc' 'orderCounter' 1}}
{
  "orderId": {{step-counter 'get' 'orderCounter'}},
  "status": "Order Created"
}

Data Store​

The Data Store acts as a key-value storage for persisting data between mock requests. It supports storing numbers, strings, and objects, making it versatile for simulating scenarios where previous request data needs to referred in future responses.

Syntax​

{{ data-store 'operation' 'keyName' value }}

Operation:

  • set: Stores a new value for the specified keyName. The value parameter is mandatory for this operation.
  • get: Retrieves the value associated with the given keyName.

Example​

In this example, the orderId from the incoming request payload is extracted and saved as lastOrder in the data store for future use. Here, in the first line, the orderId is dynamically captured from the request payload and stored in the data store with the key lastOrder.

API Response Template for POST /orders:

{{data-store 'set' 'lastOrder' (body 'orderId') }}
{
  "orderId": "{{body 'orderId'}}",
  "amount": 150.00,
  "status": "Order Placed"
}

In another API endpoint, such as /orders/latest, you can retrieve the lastOrder from the persistent data store to return the most recently placed order.

API Response Template for GET /orders/latest:

{
  "orderId": "{{data-store 'get' 'lastOrder'}}",
  "amount": 150.00
}

List​

The List helper allows you to manage collections of values such as arrays. You can add, remove, or retrieve items dynamically. Lists are particularly useful for simulating scenarios like queues, stacks, or shopping carts.

Syntax​

{{ list 'operation' 'listName' value }}

Operations​

  • push: Adds item to end of list
  • pop: Removes and returns last item from list
  • get: Retrieves item by index or entire list
  • delete: Removes item by index
  • reset: Clears the list

Example​

In the following template, the first line adds the taskName parameter from the request payload to a list named taskQueue. The response then includes the total number of tasks in the list, providing the count of values.

{{ list 'push' 'taskQueue' (body 'taskName')' }}
{
  "action": "enqueue",
  "addedTask": "{{body 'taskName'}}",
  "tasksCount": {{len (list 'get' 'taskQueue')}}
}