### Install Mockintosh on MacOS

Source: https://mockintosh.io/

Use Homebrew to install the Mockintosh application on macOS.

```bash
$ brew install up9inc/repo/mockintosh
```

--------------------------------

### Install Mockintosh on Linux

Source: https://mockintosh.io/

Use pip to install the Mockintosh Python package on Linux systems.

```bash
$ pip install -U mockintosh
```

--------------------------------

### GET /config

Source: https://mockintosh.io/Management.html

Retrieves the current configuration of the Mockintosh instance.

```APIDOC
## GET /config

### Description
Retrieves the current configuration. Supports YAML format via query parameter.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **format** (string) - Optional - Set to 'yaml' to receive the response in YAML format.
```

--------------------------------

### Generate and Run Sample Configuration

Source: https://mockintosh.io/

Commands to generate a sample configuration file and start the Mockintosh server using that file.

```bash
$ mockintosh --sample-config example.yaml
```

```bash
$ mockintosh example.yaml
```

--------------------------------

### Test Mockintosh with CURL

Source: https://mockintosh.io/

Example CURL requests to verify the mock server endpoints.

```bash
curl -v http://localhost:8888/

curl -v http://localhost:8888/api/myURLParamValue123/action

curl -v "http://localhost:8888/someMoreFields?qName1=qValue&qName2=12345" -X POST -H"X-Required-Header: someval" --data "payload"
```

--------------------------------

### Define Mockintosh services and endpoints

Source: https://mockintosh.io/

A comprehensive configuration example demonstrating service definitions, parameterized paths, request matching, and dynamic response templating.

```yaml
services:
  - name: Mock for Service1
    hostname: localhost
    port: 8000
    managementRoot: __admin  # open http://localhost:8001/__admin it in browser to see the UI  
    endpoints:

    - path: "/"  # simplest mock

    - path: "/api/users/{{param}}"  # parameterized URLs
      response: "simple string response with {{param}} included"

    - path: /comprehensive-matching-and-response
      method: POST
      queryString:
        qName1: qValue  # will only match if query string parameter exists
        qName2: "{{regEx '\\d+'}}"  # will require numeric value
      headers:
        x-required-header: someval  # will cause only requests with specific header to work
      body:
        text: "{{regEx '.+'}}"  # will require non-empty POST body
      response:  # the mocked response specification goes below
        status: 202
        body: "It worked"
        headers:
          x-response-header: "{{random.uuid4}}"  # a selection of random/dynamic functions is available
          x-query-string-value: "{{request.queryString.qName2}}"  # request parts can be referenced in response
```

--------------------------------

### Configure Google Cloud Pub/Sub via Environment Variables

Source: https://mockintosh.io/Async.html

Set the required Google Cloud environment variables before starting the Mockintosh configuration.

```bash
$ GOOGLE_APPLICATION_CREDENTIALS="/path/to/project-id-111111.json" \
    GOOGLE_CLOUD_PROJECT="project-id-111111" \
    mockintosh config.yaml
```

--------------------------------

### Example GraphQL request

Source: https://mockintosh.io/Matching.html

A sample JSON request body that matches the defined GraphQL query.

```json
{"query": "query HeroNameAndFriends {\n  hero(\n    where: {name: {_eq: \"hello\"}, _and: {age: {_gt: 30}}}\n  ) {\n    name\n    age\n    friends {\n      name\n    }\n    }\n}\n"}
```

--------------------------------

### Automatic OpenAPI Detection

Source: https://mockintosh.io/

Start Mockintosh directly with an OpenAPI Specification file without manual conversion.

```bash
$ mockintosh swagger.json
```

--------------------------------

### GET /unhandled

Source: https://mockintosh.io/Management.html

Retrieves configuration prototypes for unhandled requests.

```APIDOC
## GET /unhandled

### Description
Returns a config prototype for requests that were not matched. Supports YAML format via query parameter.

### Method
GET

### Endpoint
/unhandled

### Parameters
#### Query Parameters
- **format** (string) - Optional - Set to 'yaml' to receive the response in YAML format.
```

--------------------------------

### Asynchronous Index Configuration and Endpoint

Source: https://mockintosh.io/Async.html

Example configuration for Kafka actors and the corresponding JSON response from the /async management endpoint.

```yaml
management:
  port: 8000
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: on-demand-1
        produce:
          queue: on-demand1
          key: somekey or null
          value: "@value/from/file.json"
      - name: validate-consume-1
        consume:
          queue: another-queue-name
          group: "consumer-group"
          key: matching keys
          value: "expected value"
          capture: 10
```

```bash
$ curl http://localhost:8000/async
{
  "producers": [
    {
      "type": "kafka",
      "name": "on-demand-1",
      "index": 0,
      "queue": "on-demand1",
      "producedMessages": 0,
      "lastProduced": null
    }
  ],
  "consumers": [
    {
      "type": "kafka",
      "name": "validate-consume-1",
      "index": 0,
      "queue": "another-queue-name",
      "captured": 0,
      "consumedMessages": 0,
      "lastConsumed": null
    }
  ]
}
```

--------------------------------

### GET /async

Source: https://mockintosh.io/Async.html

Retrieves an index of all configured asynchronous producers and consumers, including their current status and message counts.

```APIDOC
## GET /async

### Description
Returns an index containing lists of all configured producers and consumers, including their type, name, queue, and message statistics.

### Method
GET

### Endpoint
/async

### Response
#### Success Response (200)
- **producers** (array) - List of configured producers
- **consumers** (array) - List of configured consumers

#### Response Example
{
  "producers": [
    {
      "type": "kafka",
      "name": "on-demand-1",
      "index": 0,
      "queue": "on-demand1",
      "producedMessages": 0,
      "lastProduced": null
    }
  ],
  "consumers": [
    {
      "type": "kafka",
      "name": "validate-consume-1",
      "index": 0,
      "queue": "another-queue-name",
      "captured": 0,
      "consumedMessages": 0,
      "lastConsumed": null
    }
  ]
}
```

--------------------------------

### Define service endpoints with various response types

Source: https://mockintosh.io/Configuring.html

Demonstrates basic endpoint configuration including default GET requests, simple string responses, and detailed file-based responses with custom headers.

```yaml
services:
  - port: 8000
    endpoints:
      - path: /  # by default, method is GET, response is HTTP 200 with empty body

      - path: /api/action1
        method: "POST"
        response: "Simple string response" # can be just response content string

      - path: /api/action2
        response: # detailed specification allows controling status code and headers
          status: 201
          body: '@subdir/response.json'
          headers:
            Content-Type: application/json
```

--------------------------------

### Test JSON Schema matching with curl

Source: https://mockintosh.io/Matching.html

Example requests to verify JSON schema matching behavior.

```bash
curl -X POST http://localhost:8001/endpoint1?param1=wrongValue \
     -H "Accept: application/json"
     -d '{"somekey": "valid"}'
```

```bash
curl -X POST http://localhost:8001/endpoint1?param1=wrongValue \
     -H "Accept: application/json"
     -d '{"somekey2": "invalid"}'
```

--------------------------------

### GET /tag

Source: https://mockintosh.io/Management.html

Retrieves the currently active tag.

```APIDOC
## GET /tag

### Description
Reports the currently active tag.

### Method
GET

### Endpoint
/tag
```

--------------------------------

### GraphQL query field variation

Source: https://mockintosh.io/Matching.html

Example showing how to select specific fields by modifying the GraphQL query definition.

```yaml
graphql-query: |
  query HeroNameAndFriends {
    hero(
      where: {name: {_eq: "{{regEx '(.*)' 'name_eq'}}"}, _and: {age: {_gt: {{regEx '(.*)' 'age_gt'}}}} }
    ) {
      name
      age
    }
  }
```

--------------------------------

### GET /traffic-log

Source: https://mockintosh.io/Management.html

Retrieves traffic logs in HAR format.

```APIDOC
## GET /traffic-log

### Description
Retrieves the recorded traffic logs in HAR format from the service or global level.

### Method
GET

### Endpoint
/traffic-log
```

--------------------------------

### GET /oas

Source: https://mockintosh.io/Management.html

Retrieves the autogenerated OpenAPI specification for the service or services.

```APIDOC
## GET /oas

### Description
Returns the autogenerated OpenAPI specification for the service or services.

### Method
GET

### Endpoint
/oas
```

--------------------------------

### GET /async/consumers/{name}

Source: https://mockintosh.io/Async.html

Retrieves the list of captured messages for a specific consumer in HAR format.

```APIDOC
## GET /async/consumers/{name}

### Description
Retrieves the list of captured messages for the specified consumer. The response is provided in HAR format, similar to traffic logs.

### Method
GET

### Endpoint
/async/consumers/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the consumer actor defined in the configuration.

### Response
#### Success Response (200)
- **messages** (array) - A list of captured messages in HAR format.
```

--------------------------------

### GET /stats

Source: https://mockintosh.io/Management.html

Retrieves statistics on served requests, services, and endpoints.

```APIDOC
## GET /stats

### Description
Returns information on request counts, service statistics, response statuses, and average processing time.

### Method
GET

### Endpoint
/stats
```

--------------------------------

### Read Resource Files

Source: https://mockintosh.io/Management.html

Retrieve lists of external files or read specific file contents via GET requests.

```http
GET /resources
```

```http
GET /resources?path=somedir/myfile.txt
```

```http
GET /resources?path=somedir/myfile.txt&format=stream
```

--------------------------------

### Date Shifting in Response Templates

Source: https://mockintosh.io/Templating.html

Example of using date manipulation functions within a JSON response body template.

```json
{
  "now": "{{ date.date '%Y-%m-%d %H:%M %f' }}",
  "1_week_back": "{{ date.date '%Y-%m-%d %H:%M %f' -604800 }}",
  "1_week_forward": "{{ date.date '%Y-%m-%d %H:%M %f' 604800 }}",
  "1_day_back": "{{ date.date '%Y-%m-%d %H:%M %f' -86400 }}",
  "1_day_forward": "{{ date.date '%Y-%m-%d %H:%M %f' 86400 }}",
  "1_hour_back": "{{ date.date '%Y-%m-%d %H:%M %f' -3600 }}",
  "1_hour_forward": "{{ date.date '%Y-%m-%d %H:%M %f' 3600 }}",
  "1_minute_back": "{{ date.date '%Y-%m-%d %H:%M %f' -60 }}",
  "1_minute_forward": "{{ date.date '%Y-%m-%d %H:%M %f' 60 }}"
}
```

--------------------------------

### Run Mockintosh in Docker

Source: https://mockintosh.io/

Execute Mockintosh as a Docker container, mapping ports and mounting a local configuration directory.

```bash
$ docker run -it -p 8000-8005:8000-8005 -v `pwd`:/tmp up9inc/mockintosh /tmp/config.json
```

--------------------------------

### Configure Google Cloud Pub/Sub Emulator

Source: https://mockintosh.io/Async.html

Set the emulator host and project ID environment variables to connect to a local Pub/Sub emulator.

```bash
$ PUBSUB_EMULATOR_HOST="localhost:8681" \
    PUBSUB_PROJECT_ID="project-id" \
    mockintosh config.yaml
```

--------------------------------

### Convert OpenAPI to Mockintosh Config

Source: https://mockintosh.io/

Transpile OpenAPI Specification files into Mockintosh configuration format using the --convert flag.

```bash
$ wget https://petstore.swagger.io/v2/swagger.json
$ mockintosh swagger.json -c new_config.json json
```

```bash
$ mockintosh swagger.json -c new_config.yaml yaml
```

--------------------------------

### Create or Update Resource Files

Source: https://mockintosh.io/Management.html

Use POST requests with form data to create or update files and directories.

```bash
POST /resources -F 'path=somedir/myfile.txt' -F 'file=hello world'
```

```bash
POST /resources -F 'somedir/myfile.txt=@myfile.txt'
```

```bash
POST /resources -F 'path=somedir/' -F 'myfile.txt=@myfile.txt'
```

--------------------------------

### Mockintosh Configuration YAML

Source: https://mockintosh.io/examples/example.yaml

Defines services, endpoints, and response templates for a Mockintosh instance. Requires the Jinja2 engine for template rendering.

```yaml
# An example of a configuration file that demonstrates
# the common features of Mockintosh.
# Run:
# $ mockintosh example.yaml

templatingEngine: Jinja2
services:
- name: Mock for Service1
  hostname: localhost
  port: 8001
  managementRoot: __admin
  endpoints:
  - path: "/"
    method: GET
    response:
      headers:
        Content-Type: "text/html; charset=UTF-8"
      body: "@templates/index.html.j2"
  - path: "/users"
    method: GET
    response:
      headers:
        Content-Type: "application/json; charset=UTF-8"
      body: "@templates/users.json.j2"
- name: Mock for Service2
  hostname: service2.example.com
  port: 8002
  endpoints:
  - path: "/companies"
    method: POST
    body:
      schema:
        type: object
        properties:
          name:
            type: string
          address:
            type: string
        required:
        - name
        - address
    response:
      headers:
        Content-Type: "application/json; charset=UTF-8"
      body: "@templates/company.json.j2"
```

--------------------------------

### Configure Google Cloud Pub/Sub with Service Account

Source: https://mockintosh.io/Async.html

Specify the gpubsub type and the project ID combined with the path to the service account JSON file.

```yaml
type: gpubsub
address: project-id-111111@/path/to/project-id-111111.json
```

--------------------------------

### Configure MQTT Service

Source: https://mockintosh.io/Async.html

Sets up an MQTT service by specifying the host and port in the address field.

```yaml
type: mqtt
address: localhost:1883
```

--------------------------------

### Configure multiple sequential responses

Source: https://mockintosh.io/Configuring.html

Shows how to provide an array of responses that cycle sequentially for each incoming request.

```yaml
response:
  - "@index.html"
  - headers:
      content-type: image/png
    body: "@subdir/image.png"
  - just some text
```

--------------------------------

### GraphQL request with variables

Source: https://mockintosh.io/Matching.html

A sample request containing both a query and variables that match the configuration.

```json
{
    "query": "query HeroNameAndFriends {\n  hero(\n    where: {name: {_eq: \"hello\"}, _and: {age: {_gt: 30}}}\n  ) {\n    name\n    city\n     }\n}\n",
    "variables": {
        "var1": "val1",
        "var2": 3
    }
}
```

--------------------------------

### Run Mockintosh with Environment Variables

Source: https://mockintosh.io/Async.html

Executes Mockintosh using environment variables for AWS authentication instead of embedding credentials in the address.

```bash
$ AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" \
    AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" \
    mockintosh config.yaml
```

--------------------------------

### Configure AMQP Backend

Source: https://mockintosh.io/Async.html

Specify the AMQP type and address. Note that 'rabbitmq' and 'activemq' are also accepted as type values.

```yaml
type: amqp
address: localhost:5672
```

--------------------------------

### Configure AMQP Properties

Source: https://mockintosh.io/Async.html

Use the amqpProperties field to set keyword arguments for pika.spec.BasicProperties.

```yaml
queue: queue1
value: '{"message":"OK"}'
amqpProperties:
  priority: 0
  delivery_mode: 2
  content_encoding: "UTF-8"
  content_type: "application/json"
headers:
  __TypeId__: "com.example.ClassName"
```

--------------------------------

### Configure Custom SSL Certificates

Source: https://mockintosh.io/Configuring.html

Provides paths to custom SSL certificate and key files for a service.

```yaml
services:
  - name: This requires 'https://' to be used by a client
    port: 443
    ssl: true
    sslCertFile: path/to/cert.crt
    sslKeyFile: path/to/cert.key
```

--------------------------------

### Use Environment Variables for Address

Source: https://mockintosh.io/Async.html

Demonstrates using templating to fetch the message bus address from an environment variable.

```yaml
address: "{{env 'KAFKA' 'localhost:9092'}}"
```

--------------------------------

### Filter Services via CLI

Source: https://mockintosh.io/

Specify a list of service names to run only those services defined in the configuration file.

```bash
$ mockintosh example.yaml 'Mock for Service1' 'Mock for Service2'
```

--------------------------------

### Match HTTP Methods

Source: https://mockintosh.io/Matching.html

Use the method keyword to define specific responses for different HTTP verbs on the same path.

```yaml
endpoints:
  - path: /
    method: PATCH
    response: Patched!
  - path: /
    method: POST
    response: Posted!
```

--------------------------------

### Enable SSL for a Service

Source: https://mockintosh.io/Configuring.html

Configures a service to use SSL by setting the ssl property to true.

```yaml
services:
  - name: This requires 'https://' to be used by a client
    port: 443
    ssl: true
```

--------------------------------

### Enable Global Management API

Source: https://mockintosh.io/Management.html

Configure a top-level management section to expose the API on a dedicated port.

```yaml
management:
  port: 8000
  # ssl: true
  # sslCertFile: "subdir/cert.pem",
  # sslKeyFile: "subdir/key.pem",
```

--------------------------------

### Configure Global Headers

Source: https://mockintosh.io/Configuring.html

Define headers that are applied to every response by adding them to the globals section of the configuration.

```yaml
globals:
  headers:
    X-Tenant-Id: "test-tenant"
    Content-Type: application/json

```

--------------------------------

### Retrieve Configuration in YAML

Source: https://mockintosh.io/Management.html

Request the current configuration in YAML format using the format query parameter.

```http
GET /config?format=yaml
```

--------------------------------

### Use Regular Expressions for Matching

Source: https://mockintosh.io/Async.html

Apply regex patterns to keys, values, and headers for flexible message validation.

```yaml
management:
  port: 8000
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: validate-consume-2
        consume:
          queue: another-queue-name
          key: "{{regEx 'prefix-(.*)'}}"
          value: "expected prefix-{{justName}}"  # see also "reactive producer" section
          headers:
            hdr-name: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}" # see also "reactive producer" section
```

--------------------------------

### array(*args)

Source: https://mockintosh.io/Templating.html

Creates an array from the provided arguments.

```APIDOC
## array(*args)

### Description
Provides array support in parameters by collecting arguments into a list.

### Usage
`{{ array 'a' 'b' 'c' 'd' 'e' }}` returns `['a', 'b', 'c', 'd', 'e']`.
```

--------------------------------

### Configure Apache Kafka Backend

Source: https://mockintosh.io/Async.html

Specify the Kafka type and address for the service configuration.

```yaml
type: kafka
address: localhost:9092
```

--------------------------------

### POST /config

Source: https://mockintosh.io/Management.html

Updates the current configuration dynamically.

```APIDOC
## POST /config

### Description
Updates the configuration dynamically. Supports YAML payload.

### Method
POST

### Endpoint
/config
```

--------------------------------

### Create an array

Source: https://mockintosh.io/Templating.html

Constructs an array from the provided arguments.

```handlebars
{{ array 'a' 'b' 'c' 'd' 'e' }}
```

--------------------------------

### Automatic Regex Conversion

Source: https://mockintosh.io/Matching.html

Mockintosh automatically converts simple variable placeholders in paths into regex functions.

```yaml
- path: "/hello-{{somevar}}/another"
  response: 'result: {{somevar}}'
```

```yaml
- path: "/{{regEx 'hello\-(.*)' 'somevar'}}/another"
  response: 'result: {{somevar}}'
```

--------------------------------

### Configure Interceptors via CLI

Source: https://mockintosh.io/

Use the --interceptor flag to register interceptor functions. PYTHONPATH can be set to include directories containing custom modules.

```bash
$ mockintosh some_config.json --interceptor=mypackage.mymodule.forbid_admin
```

```bash
$ PYTHONPATH=/some/dir mockintosh some_config.json --interceptor=mymodule.forbid_admin
```

--------------------------------

### Define Multiple Services on the Same Port

Source: https://mockintosh.io/Configuring.html

Uses hostnames to serve multiple services from a single port, enabling virtual host functionality.

```yaml
services:
  - name: "First service"
    hostname: "service1.example.com"
    port: 80
  - name: "Second service"
    hostname: "service2.example.com"
    port: 80
```

--------------------------------

### Implement Jinja2 Templating

Source: https://mockintosh.io/Configuring.html

Use Jinja2 syntax within response bodies to generate dynamic content, including support for Faker methods.

```json
{
  "users": [{% for n in range(request.queryString.total) %}
    {
      "id": {{ random.int(10000, 100000) }},
      "firstName": "{{ fake.first_name() }}",
      "lastName": "{{ fake.last_name() }}",
      "friends": [{% for n in range(range(5) | random) %}
        {
          "id": "{{ random.uuid4() }}"
        }{% if not loop.last %},{% endif %}
      {% endfor %}]
    }{% if not loop.last %},{% endif %}
  {% endfor %}],
  "total": {{ request.queryString.total }}
}
```

--------------------------------

### Configure Redis Backend

Source: https://mockintosh.io/Async.html

Specify the Redis type and address. Note that key and headers fields are ignored for this backend.

```yaml
type: redis
address: localhost:6379
```

--------------------------------

### Define Static HTTP Response

Source: https://mockintosh.io/Templating.html

Basic configuration for setting a static status, headers, and body in a Mockintosh service endpoint.

```yaml
services:
  - port: 8080
    endpoints:
      - path: /api-call
        response:
          status: 201
          headers:
            content-type: application/json
            x-custom-id: 12345
          body: '{"result": "created"}'
```

--------------------------------

### Define Response Body Source

Source: https://mockintosh.io/Templating.html

Configure the response body as a direct string or by referencing an external template file.

```yaml
response:
  body: 'hello world'
```

```yaml
response:
  body: '@some/path/my_template.json.hbs'
```

--------------------------------

### Configure Kafka Service for Mock Actors

Source: https://mockintosh.io/Async.html

Defines a service of type kafka with a broker address and SSL configuration.

```yaml
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092  # broker string of pre-existing Kafka instance
    ssl: true
    actors: [ ]  # here we will configure the actors, see below
```

--------------------------------

### Match body text with RegEx

Source: https://mockintosh.io/Matching.html

Use the regEx function within the text body field to match request content.

```yaml
services:
  - name: Mock for Service1
    port: 8001
    endpoints:
      - path: "/endpoint1"
        method: POST
        body:
          text: {{regEx '"jsonkey": "expectedval-(.+)"' 'namedValue'}}
```

--------------------------------

### Configure datasets for dynamic response templating

Source: https://mockintosh.io/Configuring.html

Uses a dataset array to inject key-value pairs into response templates, which cycles through the provided values.

```yaml
dataset:
  - var1: val1
  - var1: val2
response: 'dataset: {{var1}}'
```

--------------------------------

### Define Minimalistic Services

Source: https://mockintosh.io/Configuring.html

Basic configuration for defining multiple services with unique ports and endpoints.

```yaml
services:
  - name: Catalogue API
    port: 8001
    endpoints:
      - path: /
  - name: Cart API
    port: 8002
    endpoints:
      - path: /
```

--------------------------------

### POST /tag

Source: https://mockintosh.io/Management.html

Sets the currently active tag.

```APIDOC
## POST /tag

### Description
Sets the active tag using either the raw request body or a query parameter.

### Method
POST

### Endpoint
/tag

### Parameters
#### Query Parameters
- **current** (string) - Optional - The name of the tag or comma-separated list of tags to set.
```

--------------------------------

### env(name, default)

Source: https://mockintosh.io/Templating.html

Retrieves the value of an environment variable.

```APIDOC
## env(name, default)

### Description
Returns the value of the environment variable specified by 'name'. If the variable does not exist, the 'default' value is returned.

### Parameters
- **name** (string) - The name of the environment variable.
- **default** (string) - The value to return if the environment variable is not found.
```

--------------------------------

### Access environment variables

Source: https://mockintosh.io/Templating.html

Retrieves an environment variable by name, returning a default value if the variable is unset.

```text
env(name, default)
```

--------------------------------

### Define Performance Profiles

Source: https://mockintosh.io/Configuring.html

Configuration structure for defining probabilistic performance profiles including delay and fault distribution.

```yaml
performanceProfiles:
  profile1:
    ratio: 1
    delay: 1.5
    faults:
      '200': 0.3
      '201': 0.1
      '400': 0.1
      '500': 0.2
      '503': 0.1
      PASS: 0.4
      RST: 0.2
      FIN: 0.1
  profile2:
    ratio: 0.3
    delay: 4.8
```

--------------------------------

### POST /async/producers/{identifier}

Source: https://mockintosh.io/Async.html

Triggers an on-demand asynchronous producer by its name or index.

```APIDOC
## POST /async/producers/{identifier}

### Description
Triggers the production of a message for a configured on-demand Kafka producer.

### Method
POST

### Endpoint
/async/producers/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string/integer) - Required - The name or global index of the producer to trigger.

### Response
#### Success Response (200)
- **type** (string) - The service type (e.g., kafka)
- **name** (string) - The name of the producer
- **index** (integer) - The index of the producer
- **queue** (string) - The target queue or topic name
- **lastProduced** (float) - Timestamp of the last produced message

### Response Example
{
  "type": "kafka",
  "name": "on-demand-1",
  "index": 0,
  "queue": "on-demand1",
  "lastProduced": 1618695168.6416173
}
```

--------------------------------

### Trigger On-Demand Producer via API

Source: https://mockintosh.io/Async.html

Executes a POST request to trigger the producer by name or index.

```bash
curl -X POST http://localhost:8000/async/producers/on-demand-1
```

```bash
curl -X POST http://localhost:8000/async/producers/0
```

--------------------------------

### Match Multipart and URL-encoded bodies

Source: https://mockintosh.io/Matching.html

Use the urlencoded or multipart sections to match POST request parameters.

```yaml
services:
  - port: 8001
    endpoints:
      - path: "/body-urlencoded"
        method: POST
        body:
          urlencoded:
            param1: myValue
            param2: "{{myVar}}"
            param3: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}"
      - path: "/body-multipart"
        method: POST
        body:
          multipart:
            param1: myValue
            param2: "{{myVar}}"
            param3: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}"
```

--------------------------------

### Use Regular Expressions in Paths

Source: https://mockintosh.io/Matching.html

Incorporate regex patterns within path segments to match dynamic URL structures.

```yaml
- path: "/match/{{regEx 'prefix-.*'}}/someval"
  response: 'regex match: {{request.path}}'
```

```yaml
- path: "/match/{{regEx 'prefix-(.*)' 'myVar'}}/someval"
  response: 'regex capture group: {{myVar}}'
```

```yaml
- path: "/parameterized5/text/{{var1}}/{{regEx 'prefix-(.*)-(.*)-suffix' 'var2' 'var3'}}/{{var4}}/{{regEx 'prefix2-(.*)' 'var5'}}"
  response: 'var1: {{var1}}, var2: {{var2}}, var3: {{var3}}, var4: {{var4}}, var5: {{var5}}'
```

--------------------------------

### Configure Amazon SQS with ElasticMQ

Source: https://mockintosh.io/Async.html

Connects to a local ElasticMQ instance using the SQS-compatible interface.

```yaml
type: amazonsqs
address: http://localhost:9324#elasticmq
```

--------------------------------

### Define Parameterized Paths

Source: https://mockintosh.io/Matching.html

Use double curly braces to define path parameters that can be referenced in response templates.

```yaml
endpoints:
  - path: "/parameterized/{{myVar}}/someval"
    response: 'Here is: {{myVar}}'
```

--------------------------------

### Configure a Validating Consumer

Source: https://mockintosh.io/Async.html

Define a Kafka consumer actor with specific queue, group, key, and value expectations.

```yaml
management:
  port: 8000
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: validate-consume-1
        consume:
          queue: another-queue-name # topic/queue name to subscribe to, required
          group: "consumer-group" # optional consumer group
          key: matching keys  # expected key, optional
          value: "expected value"  # optional
          capture: 10  # limit len of messages to store for validation, optional, default: 1
```

--------------------------------

### Configure an On-Demand Kafka Producer

Source: https://mockintosh.io/Async.html

Defines a producer that waits for an external API trigger. The create flag enables automatic topic creation if it does not exist.

```yaml
management:
  port: 8000
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: on-demand-1
        produce:
          create: true
          queue: on-demand1
          key: somekey or null
          value: "@value/from/file.json"  # it's possible to reference file
```

--------------------------------

### Automatic Query String Conversion

Source: https://mockintosh.io/Matching.html

Define query parameters directly within the path string for automatic conversion to a queryString object.

```yaml
- path: "/search?q={{keyword1}}&s={{keyword2}}"
  response: 'result: {{keyword1}} {{keyword2}}'
```

```yaml
- path: "/search"
  queryString:
    q: "{{keyword1}}"
    s: "{{keyword1}}"
  response: 'result: {{keyword1}} {{keyword2}}'
```

--------------------------------

### Toggle Unhandled Requests Tracking

Source: https://mockintosh.io/Management.html

Enable or disable the recording of unmatched requests using the unhandled endpoint.

```bash
curl -X POST http://localhost:8000/unhandled -d 'true'
```

```bash
curl -X POST http://localhost:8000/unhandled -d 'false'
```

--------------------------------

### Configure Query String Matching in YAML

Source: https://mockintosh.io/Matching.html

Defines endpoint matching rules based on query parameters, including support for variable interpolation and regex capture groups.

```yaml
services:
  - name: Service1
    port: 8001
    endpoints:
      - path: "/alternative"
        method: GET
        queryString:
          param1: my Value
          param2: "{{myVar}}"
          param3: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}"
        response:
          body: 'query string match: {{request.queryString.param1}} {{myVar}} {{myCapturedVar}}'
          status: 201
      - path: "/alternative"
          queryString:
            param4: another query string
          response:
            body: 'param4 request query string: {{request.queryString.param4}}'

```

--------------------------------

### POST /traffic-log

Source: https://mockintosh.io/Management.html

Enables traffic logging for the service or global level.

```APIDOC
## POST /traffic-log

### Description
Enables traffic logging by sending a form-data request.

### Method
POST

### Endpoint
/traffic-log

### Parameters
#### Request Body
- **enable** (boolean) - Required - Set to true to enable logging.
```

--------------------------------

### Configure OAS for a Service

Source: https://mockintosh.io/Management.html

Define an external OpenAPI specification file for a service within the configuration.

```yaml
services:
  - name: Mgmt demo with OAS
    managementRoot: __admin
    oas: '@path/to/service.oas.json'
```

--------------------------------

### Match Request Headers

Source: https://mockintosh.io/Matching.html

Define required headers for an endpoint, supporting static values, variables, and regex capture groups.

```yaml
services:
  - port: 8001
    endpoints:
      - path: "/alternative"
        method: GET
        headers:
          hdr1: myValue
          hdr2: "{{myVar}}"
          hdr3: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}"
        response:
          body: 'headers match: {{request.headers.hdr1}} {{myVar}} {{myCapturedVar}}'
          status: 201
          headers:
            Set-Cookie:
              - name1={{request.headers.hdr2}}
              - name2={{request.headers.hdr3}}
      - path: "/alternative"
        headers:
          hdr4: another header
        response:
          body: 'hdr4 request header: {{request.headers.hdr4}}'
          headers:
            hdr4: 'hdr4 request header: {{request.headers.hdr4}}'
```

--------------------------------

### Define GraphQL query matching

Source: https://mockintosh.io/Matching.html

Use the graphql-query field under the body configuration to match incoming GraphQL requests with regex templates.

```yaml
services:
  - name: Mock for Service1
    port: 8001
    endpoints:
      - path: "/endpoint1"
        method: POST
        response:
          headers:
            Content-Type: application/json
          body: '@templates/resp1.json.hbs'
          useTemplating: true
        body:
          graphql-query: |
            query HeroNameAndFriends {
              hero(
                where: {name: {_eq: "{{regEx '(.*)' 'name_eq'}}"}, _and: {age: {_gt: {{regEx '(.*)' 'age_gt'}}}} }
              ) {
                name
                age
                friends {
                  name
                }
              }
            }
```

--------------------------------

### Define GraphQL variables matching

Source: https://mockintosh.io/Matching.html

Use the graphql-variables field to specify matching criteria for GraphQL variables.

```yaml
services:
  - name: Mock for Service1
    port: 8001
    endpoints:
      - path: "/endpoint1"
        method: POST
        response:
          headers:
            Content-Type: application/json
          body: '@templates/resp1.json.hbs'
          useTemplating: true
        body:
          graphql-query: |
            query HeroNameAndFriends {
              hero(
                where: {name:       {_eq: "{{regEx '(.*)' 'name_eq'}}"}, _and: {age: {_gt: {{regEx '(.*)' 'age_gt'}}}} }
              ) {
                name
                city
              }
            }
          graphql-variables:
            var1: val1
            var2: "{{regEx '\\d'}}"
```

--------------------------------

### Resources Management

Source: https://mockintosh.io/Management.html

Endpoints for reading, creating, updating, and deleting external resource files.

```APIDOC
## GET /resources

### Description
Returns the list of paths to the external files used in the configuration file, or reads the content of a specific file.

### Method
GET

### Endpoint
/resources

### Parameters
#### Query Parameters
- **path** (string) - Optional - The relative path of the file to read.
- **format** (string) - Optional - Set to 'stream' to download the file as an octet stream.

## POST /resources

### Description
Creates or updates a resource file. Directories are automatically created as needed.

### Method
POST

### Endpoint
/resources

### Parameters
#### Request Body
- **path** (string) - Required - The relative path of the file.
- **file** (string/file) - Required - The content to write to the file.

## DELETE /resources

### Description
Removes a resource file and its parent directory if empty.

### Method
DELETE

### Endpoint
/resources

### Parameters
#### Query Parameters
- **path** (string) - Required - The relative path of the file to delete.
- **keep** (boolean) - Optional - If true, prevents the removal of parent directories.
```

--------------------------------

### Multiple Payloads Configuration

Source: https://mockintosh.io/Async.html

Configures a producer to cycle through a list of payloads for each trigger.

```yaml
produce:
  - queue: topicA
    key: keyA-1
    value: valueA-1
    headers:
      hdrA-1: valA-1
  - queue: topicA
    key: keyA-2
    value: valueA-2
    headers:
      hdrA-2: valA-2
```

--------------------------------

### Reference external JSON Schema

Source: https://mockintosh.io/Matching.html

Point to an external file path for the JSON schema definition.

```yaml
services:
  - name: Mock for Service1
    port: 8001
    endpoints:
      - path: "/endpoint1"
        method: POST
        body:
          schema: "@path/to/schema.json"
```

--------------------------------

### Enable Service-Level Management API

Source: https://mockintosh.io/Management.html

Use the managementRoot property within a service definition to expose management endpoints at a specific URL path.

```yaml
services:
  - name: Mgmt demo
    managementRoot: __admin
```

--------------------------------

### Delete Resource Files

Source: https://mockintosh.io/Management.html

Remove files and optionally clean up empty parent directories.

```http
DELETE /resources?path=somedir/myfile.txt
```

--------------------------------

### Configure a Scheduled Kafka Producer

Source: https://mockintosh.io/Async.html

Defines a producer that sends messages at a fixed interval. The delay option is required to distinguish it from on-demand producers.

```yaml
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: scheduled-producer-1  # just the name
        produce:
          queue: scheduled-queue1  # topic/queue name
          key: "message key, can be null"
          value: "message value"
          headers:
            constant: justvalue
            timestamp: '{{date.timestamp}}'  # regular Mockintosh templating can be used

        delay: 5  # seconds between producing
        limit: 100  # limit of how many messages to produce, optional
```

--------------------------------

### Dataset Injection Configuration

Source: https://mockintosh.io/Async.html

Injects key-value combinations into response templates using a dataset field.

```yaml
dataset:
  - var1: val1
  - var1: val2
produce:
  - queue: topic1
    key: key1
    value: "dset: {{var1}}"
```

--------------------------------

### Configure Amazon SQS with AWS Credentials

Source: https://mockintosh.io/Async.html

Defines the connection URI for Amazon SQS using explicit AWS credentials and region.

```yaml
type: amazonsqs
address: https://<AWS_ACCESS_KEY_ID>:<AWS_SECRET_ACCESS_KEY>@us-east-2.queue.amazonaws.com:443#us-east-2
```

--------------------------------

### Convert to JSON

Source: https://mockintosh.io/Templating.html

Serializes data to JSON format. Usage differs between Jinja2 and Handlebars syntax.

```jinja2
{{ fake.random_letters() | tojson }}
```

```handlebars
{{ tojson ( fake.random_letters ) }}
```

--------------------------------

### Define Service with Hostname

Source: https://mockintosh.io/Configuring.html

Restricts a service to respond only to requests containing a specific Host HTTP header.

```yaml
services:
  - name: I'm like Google
    port: 8001
    hostname: www.google.com
    endpoints:
      - path: /
```

--------------------------------

### GraphQL response template

Source: https://mockintosh.io/Matching.html

A template used to generate the response based on captured regex variables.

```json
{
  "data": {
    "hero": {
      "name": "{{ name_eq }}",
      "age": {{ random.int age_gt 50 }},
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}
```

--------------------------------

### Tagged Payloads Configuration

Source: https://mockintosh.io/Async.html

Allows selecting specific payloads using a tag field.

```yaml
produce:
  - queue: topicA
    key: keyA-1
    value: valueA-1
    headers:
      hdrA-1: valA-1
  - queue: topicA
    tag: async-tagA-3
    key: keyA-3
    value: valueA-3
    headers:
      hdrA-3: valA-3
  - queue: topicA
    key: keyA-2
    value: valueA-2
    headers:
      hdrA-2: valA-2
```

--------------------------------

### POST /unhandled

Source: https://mockintosh.io/Management.html

Enables or disables the recording of unhandled requests.

```APIDOC
## POST /unhandled

### Description
Enables or disables the capture of unhandled requests.

### Method
POST

### Endpoint
/unhandled

### Request Body
- **data** (boolean) - Required - Set to 'true' to enable or 'false' to disable recording.
```

--------------------------------

### Generated GraphQL regex

Source: https://mockintosh.io/Matching.html

The internal regex representation generated from the graphql-query template.

```text
query\ HeroNameAndFriends\ {\
\ \ hero\(\
\ \ \ \ where:\ {name:\ {_eq:\ "(.*)"\},\ _and:\ {age:\ {_gt:\ (.*)\}}}\
\ \ )\ {\
\ \ \ \ name\
\ \ \ \ age\
\ \ \ \ friends\ {\
\ \ \ \ \ \ name\
\ \ \ \ }\
\ \ }\
}
```

--------------------------------

### Static Path Priority

Source: https://mockintosh.io/Matching.html

Static path segments take precedence over parameterized or regex-based segments during request matching.

```yaml
endpoints:
  - path: "/parameterized/{{myVar}}/someval"
    response: 'Here is: {{myVar}}'
  - path: "/parameterized/staticval/someval"
    response: static path segments have a high priority
```

--------------------------------

### Reactive Producer Configuration

Source: https://mockintosh.io/Async.html

Defines a Kafka actor that produces a message in reaction to a consumed message, with optional delay and template referencing.

```yaml
services:
  - name: Kafka Mock Actors
    type: kafka
    address: localhost:9092
    actors:
      - name: reactive-producer-1
        consume:
          queue: consume-from-topic-1
          key: "{{regEx 'prefix-(.*)'}}"
          value: "expected prefix-{{justName}}"  # see also "reactive producer" section
          headers:
            hdr-name: "{{regEx 'prefix-(.+)-suffix' 'myCapturedVar'}}" # see also "reactive producer" section
        delay: 5  # optional delay before producing
        produce:
          queue: produce-into-topic-2
          key: "can reference as {{consumed.key}} and {{consumed.value}}"
          value: "reference from consumed: {{justName}} {{myCapturedVar}}"
          headers:
            propagated-hdr: '{{consumed.headers.hdr-name}}'
```

--------------------------------

### tojson(text)

Source: https://mockintosh.io/Templating.html

Converts the input into a JSON string representation.

```APIDOC
## tojson(text)

### Description
Converts the provided text or object into a JSON string. Equivalent to the tojson filter in Jinja2.

### Usage
Jinja2: `{{ fake.random_letters() | tojson }}`
Handlebars: `{{ tojson ( fake.random_letters ) }}`
```

--------------------------------

### Query and Clear Captured Messages

Source: https://mockintosh.io/Async.html

Use the Management API to retrieve or clear messages captured by a specific consumer.

```bash
curl http://localhost:8000/async/consumers/validate-consume-1
```

```bash
curl -X DELETE http://localhost:8000/async/consumers/validate-consume-1
```

--------------------------------

### Match body with JSON Schema

Source: https://mockintosh.io/Matching.html

Define a JSON schema object to validate the request body structure.

```yaml
services:
  - name: Mock for Service1
    port: 8001
    endpoints:
      - path: "/endpoint1"
        method: POST
        body:
          schema:
            type: object
            properties:
              somekey: { }
            required:
              - somekey
        response: 'endpoint1: body JSON schema matched'
```

--------------------------------

### Retrieve Unhandled Requests in YAML

Source: https://mockintosh.io/Management.html

Query the unhandled requests endpoint with the format parameter set to yaml.

```http
GET /unhandled?format=yaml
```