Configuration Specification

Reference for the Moclojer configuration file format

This reference guide provides details about the YAML syntax for Moclojer configuration files.

Overview

Moclojer uses YAML configuration files to define mock endpoints. Each configuration file contains a list of endpoint definitions that the mock server will respond to.

Example Configuration

- endpoint:
    method: GET
    path: /hello/:username
    response:
      status: 200
      headers:
        Content-Type: application/json
      body: >
        {
          "hello": "{{path-params.username}}!"
        }

- endpoint:
    method: POST
    path: /users
    body: |
      {
        "name": "string",
        "email": "string"
      }
    response:
      status: 201
      headers:
        Content-Type: application/json
      body: >
        {
          "id": 123,
          "name": "{{json-params.name}}",
          "email": "{{json-params.email}}"
        }

Configuration File Structure

A Moclojer configuration file is a YAML file containing an array of endpoint objects.

Endpoint

Each endpoint object has the following structure:

Key	Required	Type	Description
endpoint	Yes	Object	Contains the configuration for this mock endpoint

Endpoint Object

Key	Required	Type	Description
method	No	String	HTTP method for this endpoint. Default: GET
host	No	String	Domain this endpoint should respond to. Used with multi-domain support
path	Yes	String	URL path pattern with optional parameter types (e.g., /users/:id|int)
query	No	Object	Query parameter definitions with types
body	No	String/Object	Expected request body schema
response	Yes	Object	Response configuration
rate-limit	No	Object	Rate limiting configuration for this endpoint
webhook	No	Object	Webhook configuration to trigger after handling the request

Path Parameters

Moclojer supports typed path parameters using the syntax :paramName\|type:

path: /users/:id|int/posts/:slug|string

Available types:

• string (default)

• int

• uuid

• date

• boolean

Query Parameters

Query parameters can be defined and validated:

query:
  limit: int
  offset: int
  search: string

Response Object

Key	Required	Type	Description
status	No	Integer	HTTP status code. Default: 200
headers	No	Object	HTTP response headers
body	No	String/Object	Response body content
external-body	No	Object	External body configuration for loading response from external source

Templates

Moclojer supports templates in the response body using the Handlebars-like syntax:

body: >
  {
    "user": "{{path-params.username}}",
    "queryParam": "{{query-params.q}}",
    "jsonData": "{{json-params.field}}"
  }

Available template variables:

• path-params: URL path parameters

• query-params: URL query parameters

• json-params: JSON body parameters

• header-params: Request headers

Rate Limiting

Rate limiting can be configured per endpoint:

rate-limit:
  window-ms: 60000    # 1 minute window
  max-requests: 10    # Allow 10 requests per window
  key-fn: remote-addr # Use client IP as the rate limit key

Key	Required	Type	Description
window-ms	No	Integer	Time window in milliseconds. Default: 900000 (15 minutes)
max-requests	No	Integer	Maximum requests per window. Default: 100
key-fn	No	String	Function to determine rate limit key. Default: remote-addr

Webhook

Configure webhooks to be triggered after handling a request:

webhook:
  sleep-time: 60      # Sleep time in seconds before triggering webhook
  url: https://example.com/webhook
  method: POST
  body: >
    {"id": 123, "status": "processed"}
  if: path-params.project-name = "moclojer"  # Conditional trigger

Key	Required	Type	Description
sleep-time	No	Integer	Delay in seconds before triggering webhook
url	Yes	String	Webhook URL
method	No	String	HTTP method for webhook. Default: POST
body	No	String/Object	Webhook request body
if	No	String	Conditional expression for triggering webhook

WebSocket

Configure WebSocket endpoints for real-time bidirectional communication:

- websocket:
    path: /ws/chat/:room_id
    on-connect:
      response: >
        {"status": "connected", "room": "{{path-params.room_id}}"}
    on-message:
      - pattern: "ping"
        response: "pong"
      - pattern: "join"
        response: >
          {"event": "joined", "user": "{{json-params.user}}", "room": "{{path-params.room_id}}"}

WebSocket Object

Key	Required	Type	Description
path	Yes	String	URL path for the WebSocket endpoint
on-connect	No	Object	Configuration for when a client connects
on-message	No	Array	List of patterns and responses for messages

on-connect Object

Key	Required	Type	Description
response	Yes	String/Object	Response sent to the client upon connection

on-message Object

Each item in the on-message list is an object with the following fields:

Key	Required	Type	Description
pattern	Yes	String	Pattern to match against the received message
response	Yes	String/Object	Response to be sent when the message matches the pattern

Templates in WebSockets

Like HTTP responses, you can use templates in WebSocket responses:

- websocket:
    path: /ws/users/:user_id
    on-connect:
      response: >
        {"status": "connected", "user": "{{path-params.user_id}}"}
    on-message:
      - pattern: "{\"action\":\"update\"}"
        response: >
          {"event": "updated", "user": "{{path-params.user_id}}", "data": {{message}}}

Available template variables:

• path-params: URL path parameters

• query-params: URL query parameters

• json-params: JSON body parameters (for JSON messages)

• message: The complete received message

External Body

Load response body from external sources:

external-body:
  provider: json
  path: path/to/response.json

external-body:
  provider: json
  path: https://api.example.com/data

Key	Required	Type	Description
provider	Yes	String	Provider type (json, yaml, xml, etc.)
path	Yes	String	Path to external resource (file or URL)

Multiple Domains Support

Moclojer can handle multiple domains in a single configuration:

- endpoint:
    host: api.example.com
    method: GET
    path: /v1/resource
    response:
      status: 200
      body: '{"domain": "api.example.com"}'

- endpoint:
    host: admin.example.com
    method: GET
    path: /v1/resource
    response:
      status: 200
      body: '{"domain": "admin.example.com"}'

Full Configuration Example

- endpoint:
    method: GET
    path: /users/:id|int
    query:
      fields: string
    response:
      status: 200
      headers:
        Content-Type: application/json
      body: >
        {
          "id": {{path-params.id}},
          "name": "User {{path-params.id}}",
          "fields": "{{query-params.fields}}"
        }
    rate-limit:
      window-ms: 60000
      max-requests: 100

- endpoint:
    method: POST
    path: /users
    body: |
      {
        "name": "string",
        "email": "string"
      }
    response:
      status: 201
      headers:
        Content-Type: application/json
      body: >
        {
          "id": 123,
          "name": "{{json-params.name}}",
          "email": "{{json-params.email}}"
        }
    webhook:
      sleep-time: 5
      url: https://webhook.example.com/new-user
      method: POST
      body: >
        {"userId": 123, "name": "{{json-params.name}}"}

- endpoint:
    host: api.example.com
    method: GET
    path: /products/:id|int
    response:
      status: 200
      external-body:
        provider: json
        path: data/products/{{path-params.id}}.json