stubby4j

https://stubby4j.com
Admin
stubby4j is an HTTP/1.1, HTTP/2, and WebSockets API stub server for testing service-oriented and...
Tokens:21,844
Snippets:222
Trust Score:5.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Full HTTP Endpoint Configuration Example

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

An example of a fully populated, though unrealistic, endpoint configuration in YAML format. It demonstrates various request and response properties.

```yaml
-  description: Optional description shown in logs
   uuid: fdkfsd8f8ds7f
   request:
      url: ^/your/awesome/endpoint$
      method: POST
      query:
         exclamation: post requests can have query strings!
      headers:
         content-type: application/xml
      post: >
         <!xml blah="blah blah blah">
         <envelope>
            <unaryTag/>
         </envelope>
      file: tryMyFirst.xml

   response:
      status: 200
      latency: 5000
      headers:
         content-type: application/xml
         server: stubbedServer/4.2
      body: >
         <!xml blah="blah blah blah">
         <responseXML>
            <content></content>
         </responseXML>
      file: responseData.xml

```

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

### Install stubby4j SNAPSHOT to local .m2 repository

Source: https://stubby4j.com/

Run this Gradle command to build and install stubby4j snapshot artifacts to your local Maven repository.

```bash
./gradlew clean build publishToMavenLocal
```

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

### Simplest Endpoint Configuration

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

The most basic endpoint configuration requires only a URL. This example uses a root path.

```yaml
-  request:
      url: /

```

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

### Get Default Proxy Configuration

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve the default proxy configuration.

```APIDOC
## GET /proxy-config/default

### Description
Retrieves the default proxy configuration.

### Method
GET

### Endpoint
/proxy-config/default

### Response
#### Success Response (200)
- **text/plain;charset=UTF-8**: YAML string representing the default proxy configuration.

#### Error Response (400)
- **application/json**: {"code":"400","message":"Bad Request"}

### Request Example
```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/default
```
```

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

### Start stubby4j programmatically (Yamless)

Source: https://stubby4j.com/

When running stubby4j as an embedded JAR, you can manage stubs programmatically using `StubbyClient`. The `startJettyYamless` method allows providing stubs configuration as a String payload, bypassing the need for a physical YAML file.

```java
StubbyClient.startJettyYamless(yamlPayload)
```

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

### Get Proxy Configuration by UUID

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a proxy configuration by its UUID.

```APIDOC
## GET /proxy-config/{uuid}

### Description
Retrieves a proxy configuration by its UUID.

### Method
GET

### Endpoint
/proxy-config/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the proxy configuration.

### Response
#### Success Response (200)
- **text/plain;charset=UTF-8**: YAML string representing the proxy configuration.

#### Error Response (400)
- **application/json**: {"code":"400","message":"Bad Request"}
```

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

### Endpoint Configuration with Specific HTTP Method

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Specify a single HTTP method for an endpoint. Defaults to GET if not provided.

```yaml
-  request:
      url: /anything
      method: GET

```

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

### Get Proxy Config by UUID

Source: https://stubby4j.com/docs/admin_portal.html

Retrieves a specific proxy configuration using its unique identifier (UUID). Ensure the UUID is valid and corresponds to an existing configuration.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/some-unique-uuid-string
```

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

### Template File Path with Regex Tokens

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Use regex capturing groups to dynamically set the file path for responses. Ensure the regex has capturing groups for token IDs starting from 1.

```yaml
- request:
    method: [GET]
    url: ^/regex-fileserver/([a-z]+).html$

 response:
    status: 200
    file: ../html/<% url.1 %>.html

```

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

### Get Default Proxy Config (YAML)

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve the default proxy configuration using this cURL command. This configuration is essential for catch-all scenarios and cannot be deleted.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/default
```

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

### Docker Compose for stubby4j JRE11

Source: https://stubby4j.com/

Configure Docker Compose to include stubby4j with JRE11. This setup maps local YAML files, sets environment variables for ports and configuration, and enables specific command-line arguments.

```yaml
# This compose file adds stubby4j https://hub.docker.com/r/azagniotov/stubby4j to your stack
#
# See "Environment variables" section at https://hub.docker.com/r/azagniotov/stubby4j
version: '3.5'
services:
  stubby4j-jre11:
    # 'root' - so that stubby4j can write 'logs' into host machine's directory mapped to container volume
    user: root
    image: azagniotov/stubby4j:latest-jre11
    volumes:
      - "./yaml:/home/stubby4j/data"
    container_name: stubby4j_jre11
    ports:
      - 8884:8884
      - 8891:8891
      - 7445:7445
    environment:
      YAML_CONFIG: smoke-tests-stubs.yaml
      LOCATION: 0.0.0.0
      STUBS_PORT: 8884
      ADMIN_PORT: 8891
      STUBS_TLS_PORT: 7445
      # https://stubby4j.com/#command-line-switches
      WITH_ARGS: "--enable_tls_with_alpn_and_http_2 --debug --watch"

```

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

### Get Stub by Numeric ID

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a specific stub configuration by its numeric ID.

```APIDOC
## GET /{stub_numeric_id}

### Description
Retrieves a stub by its numeric ID.

### Method
GET

### Endpoint
`/{stub_numeric_id}`

### Parameters
#### Path Parameters
- **stub_numeric_id** (integer) - Required - The specific stub numeric ID.

### Response
#### Success Response (200)
- **text/plain;charset=UTF-8**: YAML string representing the stub configuration.

#### Error Response (400)
- **application/json**: {"code":"400","message":"Bad Request"}

### Request Example
```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/0
```
```

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

### Get Stub by UUID

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a specific stub configuration by its unique identifier (UUID).

```APIDOC
## GET /{uuid}

### Description
Retrieves a stub by its defined UUID.

### Method
GET

### Endpoint
`/{uuid}`

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The specific stub unique identifier.

### Response
#### Success Response (200)
- **text/plain;charset=UTF-8**: YAML string representing the stub configuration.

#### Error Response (400)
- **application/json**: {"code":"400","message":"Bad Request"}

### Request Example
```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/some-unique-uuid-string
```
```

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

### Get Proxy Config by UUID

Source: https://stubby4j.com/docs/admin_portal.html

Retrieves a specific proxy configuration by its unique identifier (UUID).

```APIDOC
## GET /proxy-config/{uuid}

### Description
Retrieves a specific proxy configuration by its unique identifier.

### Method
GET

### Endpoint
/proxy-config/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The specific proxy config unique idendifier (See request_proxying.md “uuid”)

### Responses
#### Success Response (200)
- **text/plain;charset=UTF-8** - YAML string

#### Error Response (400)
- **application/json** - `{"code":"400","message":"Bad Request"}`

### Request Example
```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/some-unique-uuid-string
```
```

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

### Get Proxy Config by UUID (YAML)

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a specific proxy configuration by its UUID using this cURL command. Proxy configurations can only be updated or retrieved using their UUID.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/proxy-config/{uuid}
```

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

### Match POST requests to root URL

Source: https://stubby4j.com/

This YAML configuration defines an endpoint that matches any POST request to the root URL ('/'). The request can have any headers or post body. The method defaults to GET if not specified.

```yaml
-  request:
      url: /
      method: POST
   response: {}
```

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

### Template Response Body with POST Data Tokens

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Extract data from the POST request body using regex capturing groups and interpolate them into the response body. Tokens starting from 1 correspond to capturing groups.

```yaml
- request:
    method: POST
    url: /post-body-as-json
    headers:
       content-type: application/json
    post: >
       {"userId":"19","requestId":"(.*)","transactionDate":"(.*)","transactionTime":"(.*)"}

 response:
    headers:
       content-type: application/json
    status: 200
    body: >
       {"requestId": "<%post.1%>", "transactionDate": "<%post.2%>", "transactionTime": "<%post.3%>"}

```

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

### Single Stub with Multiple Proxy Configs Payload (JSON)

Source: https://stubby4j.com/docs/admin_portal.html

This JSON array demonstrates a single stub definition that includes multiple proxy configurations. It's used for managing complex proxy setups via the POST/PUT API.

```json
[
  {
    "request": {
      "url": "/resources/something/new",
      "query": {
        "someKey": "someValue"
      },
      "method": [
        "GET"
      ]
    },
    "response": {
      "body": "OK",
      "headers": {
        "content-type": "application/xml"
      },
      "status": 201
    }
  },
  {
    "proxy-config": {
      "description": "this would be the default proxy config",
      "strategy": "as-is",
      "properties": {
        "endpoint": "https://google.com"
      }
    }
  },
  {
    "proxy-config": {
      "uuid": "some-unique-name-1",
      "strategy": "as-is",
      "properties": {
        "endpoint": "https://yahoo.com"
      }
    }
  },
  {
    "proxy-config": {
      "description": "this would be the 2nd description",
      "uuid": "some-unique-name-2",
      "strategy": "as-is",
      "properties": {
        "endpoint": "https://microsoft.com"
      }
    }
  }
]
```

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

### List Stubs and Proxy Configurations

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve all in-memory stubs and proxy configurations as a YAML string.

```APIDOC
## GET /

### Description
Lists all in-memory stubs and proxy configurations as a YAML string.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **text/plain;charset=UTF-8**: YAML string representing all configurations.

### Request Example
```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/
```
```

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

### Multiple Stubs with Descriptions

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Demonstrates how to use the 'description' field to differentiate between multiple stubs configured for the same endpoint. This is useful for logging and clarity when many stubs are loaded.

```yaml
-  description: Stub one
   request:
      url: ^/one$
      method: GET

   response:
      status: 200
      latency: 100
      body: 'One!'

-  description: Stub two
   request:
      url: ^/two$
      method: GET

   response:
      status: 200
      latency: 100
      body: 'Two!'

-  request:
      url: ^/three$
      method: GET

   response:
      status: 200
      latency: 100
      body: 'Three!'

```

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

### Run stubby4j JAR with YAML config

Source: https://stubby4j.com/

Execute the downloaded stubby4j JAR with a local YAML configuration file. Ensure the YAML file is correctly formatted.

```bash
java -jar stubby4j-x.x.xx.jar -d <PATH_TO_LOCAL_YAML_CONFIG>
```

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

### List All Stubs & Proxy Configs (YAML)

Source: https://stubby4j.com/docs/admin_portal.html

Use this cURL command to retrieve all in-memory stubs and proxy configurations as a YAML string. The response will have a content type of text/plain.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/
```

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

### Build stubby4j Docker image from master

Source: https://stubby4j.com/

Build a Docker image for stubby4j from the master branch. This command uses default settings and might not be suitable for specific tagged releases.

```bash
$ docker build --rm --no-cache -t stubby4j:latest .
```

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

### Create/Overwrite Stubs and Proxy Configurations

Source: https://stubby4j.com/docs/admin_portal.html

Use this endpoint to create new stubs and proxy configurations or overwrite existing ones. The request body can be in JSON or YAML format.

```APIDOC
## POST /

### Description
Creates new stubs and proxy configurations or overwrites existing ones.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **(object)** - Required - JSON or YAML format representing the stub/proxy configuration.

### Request Example
```bash
curl -X POST -H "Content-Type: application/json" --data @post.json http://localhost:8889/
```

### Response
#### Success Response (201)
- **text/plain;charset=UTF-8**: Configuration created successfully

#### Error Response (400)
- **application/json**: {"code":"400","message":"Bad Request"}
```

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

### Main YAML Config with Includes

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Use this structure to include multiple sub-config YAML files into your main configuration. This helps organize a large number of stubs.

```yaml
includes:
   - service-1-stubs.yaml
   - service-2-stubs.yaml
   - ...
   - ...
   - service-N-stubs.yaml
```

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

### Endpoint Configuration with Regular Expressions

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Utilize regular expressions to define flexible URL matching patterns for endpoints.

```yaml
-  request:
      url: ^/has/to/begin/with/this/

```

```yaml
-  request:
      url: /has/to/end/with/this/$

```

```yaml
-  request:
      url: ^/must/be/this/exactly/with/optional/trailing/slash/?$

```

```yaml
-  request:
      url: ^/[a-z]{3}-[a-z]{3}/[0-9]{2}/[A-Z]{2}/[a-z0-9]+$

```

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

### Get Stub by UUID (YAML)

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a specific stub configuration by its unique identifier (UUID) using this cURL command. This is a more robust method than using the numeric ID.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/some-unique-uuid-string
```

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

### Endpoint Configuration with Multiple HTTP Methods

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure an endpoint to accept multiple HTTP methods using an array.

```yaml
-  request:
      url: /anything
      method: [GET, HEAD]

```

```yaml
-  request:
      url: /anything
      method:
         -  GET
         -  HEAD

```

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

### Record and Replay External URL

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

When the response body is a URL starting with http(s), stubby4j will record the response from that URL and replay it on subsequent calls. This is useful for dynamic external content.

```yaml
- request:
      method: [GET]
      url: /maps/api/geocode/json
      query:
         address: "1600%20Amphitheatre%20Parkway,%20Mountain%20View,%20CA"
         sensor: false

   response:
      status: 200
      headers:
         content-type: application/json
      body: http://maps.googleapis.com

```

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

### Provide Stubby4j Certificate to cURL

Source: https://stubby4j.com/

Use the `--cacert` option with cURL to specify a certificate file for verifying the server's identity. This is more secure than bypassing verification.

```shell
curl -X GET --tls-max 1.0 https://localhost:7443/hello -v \   --cacert src/main/resources/ssl/openssl.downloaded.stubby4j.self.signed.v3.pem 
```

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

### Endpoint Configuration Without Regular Expressions

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure an endpoint to match a literal URL path without using regular expressions.

```yaml
-  request:
      url: /some/resource/that/will/be/fully/matched

```

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

### Configure Multiple Websocket Objects

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Define multiple websocket configurations within a single YAML file. Each 'web-socket' object can have its own unique URL and message handling logic.

```yaml
- web-socket:
    description: this is a web-socket config
    url: /demo/web-socket/1
    sub-protocols: echo, mamba, zumba

    on-open:
      policy: once
      message-type: text
      body: You have been successfully connected
      delay: 200

    on-message:
      - client-request:
          message-type: text
          body: do push
        server-response:
          policy: push
          message-type: text
          body: pushing
          delay: 200

      - client-request:
          message-type: text
          body: hello
        server-response:
          policy: once
          message-type: text
          body: bye-bye
          delay: 250

      - client-request:
          message-type: text
          body: disconnect with a message
        server-response:
          policy: disconnect
          message-type: text
          body: bon-voyage
          delay: 250

- web-socket:
    url: /demo/web-socket/2
    sub-protocols: echo, mamba, zumba

    on-open:
      policy: once
      message-type: text
      body: You have been successfully connected

    on-message:
      - client-request:
          message-type: text
          body: send-big-json
        server-response:
          policy: once
          message-type: binary
          file: ../json/response/json_response_1.json
          delay: 250

      - client-request:
          message-type: text
          body: push-pdf-to-me
        server-response:
          policy: push
          message-type: binary
          file: ../binary/hello-world.pdf
          delay: 500


- web-socket:
    url: /demo/web-socket/3
    sub-protocols: echo, mamba, zumba

    on-open:
      policy: once
      message-type: binary
      file: ../binary/hello-world.pdf
      delay: 200


- web-socket:
    url: /demo/web-socket/4

    on-message:
      - client-request:
          message-type: binary
          file: ../binary/hello-world.pdf
        server-response:
          policy: once
          message-type: binary
          file: ../binary/hello-world.pdf
          delay: 500

      - client-request:
          message-type: binary
          file: ../json/response/json_response_6.json
        server-response:
          policy: once
          message-type: binary
          file: ../binary/hello-world.pdf
          delay: 500

- web-socket:
    url: /demo/web-socket/5

    on-message:
      - client-request:
          message-type: text
          body: send-fragmentation-pls
        server-response:
          policy: fragmentation
          message-type: binary
          file: ../json/response/json_response_1.json
          delay: 10

```

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

### Get Stub by Numeric ID (YAML)

Source: https://stubby4j.com/docs/admin_portal.html

Retrieve a specific stub configuration by its numeric ID using this cURL command. The ID can be found in the status page YAML output. The response is a YAML string.

```bash
curl -X GET -H "Content-Type: application/json" http://localhost:8889/0
```

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

### YAML Proxy Configuration with Additive Headers

Source: https://stubby4j.com/docs/request_proxying.html

Defines a proxy configuration with an additive strategy, specifying an endpoint and custom headers to be added to the proxied request. Ensure 'uuid' is unique if multiple configurations are present.

```yaml
- proxy-config:
    uuid: some-other-unique-name
    strategy: additive
    properties:
      endpoint: https://jsonplaceholder.typicode.com
    headers:
      content-type: application/json+special
      x-custom-header: something/unique
      x-custom-header-2: another/thing

```

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

### Build stubby4j Docker image from specific tag

Source: https://stubby4j.com/

Build a Docker image for stubby4j from a specific Git tag. Use the --build-arg REVISION to specify the tag, ensuring you match the image tag.

```bash
$ docker build --build-arg REVISION=v7.5.2 --rm --no-cache -t stubby4j:7.5.2 .
```

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

### Run Gradle clean and tests

Source: https://stubby4j.com/

Execute Gradle tasks to clean the project and run unit, integration, and functional tests without generating code coverage reports.

```bash
./gradlew clean
```

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

### External YAML Configuration Includes

Source: https://stubby4j.com/docs/request_proxying.html

For better organization, you can split your stubby4j configuration into multiple files, using 'includes' to reference them.

```yaml
includes:
  - include-all-test-stubs.yaml
  - include-proxy-config.yaml

```

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

### Create/Overwrite Stubs & Proxy Configs (JSON)

Source: https://stubby4j.com/docs/admin_portal.html

Use this cURL command to create new or overwrite existing stubs and proxy configurations by sending a JSON payload. Ensure the content type is set to application/json.

```bash
curl -X POST -H "Content-Type: application/json" --data @post.json http://localhost:8889/
```

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

### Configure Gradle for Sonatype snapshot repository

Source: https://stubby4j.com/

Add this repository configuration to your Gradle build file to access stubby4j snapshot versions.

```gradle
repositories {
    maven {
        url 'https://oss.sonatype.org/content/repositories/snapshots/'
    }
}
```

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

### Run Gradle clean, tests, and JaCoCo report

Source: https://stubby4j.com/

Execute Gradle tasks to clean the project, run tests, and generate a JaCoCo code coverage report. The report will be available at the specified HTML path.

```bash
./gradlew clean jacocoTestReport
```

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

### Include Websocket Config from Separate File

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Organize your configuration by including websocket definitions from a separate YAML file using the 'includes' directive. This promotes logical separation.

```yaml
includes:
  - include-all-test-stubs.yaml
  - include-web-socket-config.yaml

```

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

### Multiple Proxy Configurations in YAML

Source: https://stubby4j.com/docs/request_proxying.html

Define multiple proxy configurations in your stubby4j YAML file. The 'default proxy config' acts as a catch-all for unmatched requests, while others can be selected at runtime.

```yaml
- proxy-config:
    description: this is a default proxy config that serves as a catch-all for non-matched requests
    strategy: as-is
    properties:
      endpoint: https://jsonplaceholder.typicode.com


- proxy-config:
    uuid: some-very-unique-string
    description: this is a non-default proxy config which hits Google
    strategy: as-is
    properties:
      endpoint: https://google.com
      

- proxy-config:
    uuid: another-very-unique-string
    description: this is a non-default proxy config which hits Yahoo
    strategy: as-is
    properties:
      endpoint: https://yahoo.com

```

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

### Stubbing Basic Authorization Header

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure a stub for Basic authentication by providing the username and password directly. Stubby internally encodes this to Base64.

```yaml
-  request:
      url: ^/path/to/basic$
      method: GET
      headers:
         # no "Basic" prefix nor explicit encoding in Base64 is required when stubbing,
         # just plain username:password format. Stubby internally encodes the value in Base64
         authorization-basic: "bob:password" 
   response:
      headers:
         Content-Type: application/json
      status: 200
      body: Your request with Basic was successfully authorized!
```

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

### Delete All Configurations

Source: https://stubby4j.com/docs/admin_portal.html

Deletes all in-memory stub and proxy configurations.

```APIDOC
## DELETE /

### Description
Deletes all in-memory stub and proxy configurations.

### Method
DELETE

### Endpoint
/

### Responses
#### Success Response (200)
- **text/plain;charset=UTF-8** - `All in-memory YAML config was deleted successfully`

### Request Example
```bash
curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/
```
```

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

### Enable HTTP/2 over TLS

Source: https://stubby4j.com/

To enable HTTP/2 support for HTTPS URIs, provide the `--enable_tls_with_alpn_and_http_2` flag when running the stubby4j JAR. This flag enables HTTP/2 only for the TLS layer and requires clients to use the ALPN TLS extension. HTTP/2 over TLS is supported for TLSv1.2+ and JDK 1.8 (build 1.8.0_252) or higher.

```bash
stubby4j --enable_tls_with_alpn_and_http_2
```

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

### Query Parameter Matching for Parameters Without Values

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure matching for query parameters that are present but have no assigned value, or an empty string value.

```yaml
-  request:
      url: ^/with/parameters$
      query:
         search:
         filter: month

```

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

### Configure a Single Response for an Endpoint

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Define a basic request-response pair. This is the simplest form of endpoint configuration.

```yaml
-  request:
      method: [GET,POST]
      url: /invoice/123

   response:
      status: 201
      headers:
         content-type: application/json
      body: OK

```

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

### Use Local File for Response Body

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Specify a local file to serve as the response body. The `file` property takes precedence over `body`. Supports binary files.

```yaml
response:
      status: 200
      headers:
         content-type: application/json
      file: ../json/response.json

```

```yaml
-  request:
      url: /
   response:
      file: extremelyLongJsonFile.json

```

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

### Multiple WebSocket Configurations in YAML

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Define multiple WebSocket stubs in your stubby4j YAML configuration. Each 'web-socket' entry must have a unique 'url' property.

```yaml
- web-socket:
    url: /demo/web-socket/1
    ...
    ...
    
- web-socket:
    url: /demo/web-socket/2
    ...
    ...


```

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

### Configure WebSocket Sub-protocols

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Specify a comma-separated list of sub-protocol names for WebSocket connections. These are matched against the client's `Sec-WebSocket-Protocol` header during handshake.

```yaml
- web-socket:
    url: /demo/web-socket/1
    sub-protocols: echo, mamba, zumba
    ...
    ...

```

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

### Query Parameter Matching with Regular Expressions

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure an endpoint to match specific query parameters using regular expressions for advanced filtering.

```yaml
-  request:
      method: GET
      url: ^/with/parameters$
      query:
         type_name: user
         client_id: id
         client_secret: secret
         random_id: "^sequence"-/\d/"
         session_id: "^user_\d{32}_local"
         attributes: '["id","uuid","created","lastUpdated","displayName","email","givenName","familyName"]'

```

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

### Configure Server Response with File and Delay

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Define a WebSocket server response using a JSON file for the body and specifying a delay before sending. This snippet demonstrates `file`, `delay`, and `message-type` properties for `server-response`.

```yaml
- web-socket:
    ...
    ...

    on-message:
      - client-request:
          ...
          ...
        server-response:
          policy: fragmentation
          message-type: binary
          file: ../json/response/json_response_1.json
          delay: 10


```

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

### Mix Websocket Config with HTTP Stubs

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Integrate websocket configurations directly within the same YAML file as other stubby4j configurations like 'proxy-config', 'request', and 'response'.

```yaml
- proxy-config:
    uuid: default
    description: this is a default catch-all config
    strategy: as-is
    properties:
      endpoint: https://jsonplaceholder.typicode.com


- request:
    method:
      - GET
    url: /resources/user/1

  response:
    status: 200
    body: >
      {"status": "OK"}
    headers:
      content-type: application/json


- web-socket:
    url: /demo/web-socket/5

    on-message:
      - client-request:
          message-type: text
          body: send-fragmentation-pls
        server-response:
          policy: fragmentation
          message-type: binary
          file: ../json/response/json_response_1.json
          delay: 10

```

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

### Mixed Stubs and Proxy Configurations in YAML

Source: https://stubby4j.com/docs/request_proxying.html

It's valid to combine stub definitions (request/response) with proxy configurations within the same YAML file for logical grouping.

```yaml
- proxy-config:
    uuid: default
    description: this is a default catch-all config
    strategy: as-is
    properties:
      endpoint: https://jsonplaceholder.typicode.com


- request:
    method:
      - GET
    url: /resources/user/1

  response:
    status: 200
    body: >
      {"status": "OK"}
    headers:
      content-type: application/json


- proxy-config:
    uuid: some-other-unique-name
    strategy: as-is
    properties:
      endpoint: https://jsonplaceholder.typicode.com

```

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

### Match specific headers with regex

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Configure endpoint to accept requests with specific headers, including regular expression matching for header values. If stubbed, only these headers will be matched.

```yaml
-  request:
      url: /post/json
      method: post
      headers:
         content-type: application/json
         x-custom-header: "^this/is/\d/test"
         x-custom-header-2: "^[a-z]{4}_\d{32}_(local|remote)"

```

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

### Sequenced WebSocket Server Responses

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Configure multiple, sequenced server responses for a single WebSocket stub. Each incoming request triggers the next response in the list, cycling back to the beginning after the last one.

```yaml
- web-socket:
    ...
    ...

    on-open:
      ...
      ...

    on-message:
      - client-request:
          message-type: text
          body: Hello, World!

        server-response:
          - policy: once
            message-type: text
            body: hello-world-0
            delay: 20

          - policy: once
            message-type: text
            body: hello-world-1
            delay: 30

          - policy: fragmentation
            message-type: binary
            body: hello-world-2,hello-world-2a and hello-world-2c
            delay: 40

          - policy: once
            message-type: text
            body: hello-world-3
            delay: 50


```

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

### Delete All Stubs and Proxy Configs

Source: https://stubby4j.com/docs/admin_portal.html

Deletes all in-memory stub and proxy configurations. This operation resets the server's configuration to its initial state. Use with caution as it affects all active configurations.

```bash
curl -X DELETE -H "Content-Type: application/json" http://localhost:8889/
```

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

### Configure Sequenced Responses for an Endpoint

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Define multiple responses for a single request URI. Responses are served in a cycle, restarting after the last one is sent.

```yaml
-  request:
      method: [GET]
      url: /uri/with/sequenced/responses

   response:
      -  status: 201
         headers:
            content-type: application/json
         body: OK

      -  status: 201
         headers:
            content-stype: application/json
         body: Still going strong!

      -  status: 500
         headers:
            content-type: application/json
         body: OMG!!!

```

```yaml
-  request:
      method: [GET]
      url: /uri/with/sequenced/responses/infile

   response:
      -  status: 201
         headers:
            content-type: application/json
         file: ../json/sequenced.response.ok.json

      -  status: 201
         headers:
            content-stype: application/json
         file: ../json/sequenced.response.goingstrong.json

      -  status: 500
         headers:
            content-type: application/json
         file: ../json/sequenced.response.omfg.json

```

```yaml
-  request:
      method: [GET]
      url: /uri/with/single/sequenced/response

   response:
      -  status: 201
         headers:
            content-stype: application/json
         body: Still going strong!

```

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

### Configure Binary Message Type with File Payload

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Use 'message-type: binary' to send event payloads as bytes. The 'file' property specifies a local file path containing the payload, which takes precedence over the 'body' property.

```yaml
- web-socket:
    ...
    ...

    on-open:
      ...
      message-type: binary
      file: ../json/extremelyLongJsonFile.json
      ...


```

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

### Match POST form data

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Use the 'post' property to match specific form data in a POST request. The value can be a literal string or a regular expression.

```yaml
-  request:
      url: ^/post/form/data$
      post: name=John&email=john@example.com

```

```yaml
-  request:
      method: [POST]
      url: /uri/with/post/regex
      post: "^[\.,'a-zA-Z\s+]*$"

```

```yaml
-  request:
      url: ^/post/form/data$
      post: "^this/is/\d/post/body"

```

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

### Configure Response Headers

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Set custom headers in the stubbed response. The `x-stubby-resource-id` header is added by default.

```yaml
-  request:
      url: ^/give/me/some/json$
   response:
      headers:
         content-type: application/json
      body: >
         [{"name":"John",
            "email":"john@example.com"
         },{
            "name":"Jane",
            "email":"jane@example.com"
         }]
```

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

### Dynamic Token Replacement with Regex Capturing Groups

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Use regex capturing groups from the request URL, query parameters, or headers to dynamically populate response properties like body, header values, or file content.

```yaml
-  request:
      method: [GET]
      url: ^/regex-fileserver/([a-z]+).html$
   response:
      status: 200
      file: ../html/<% url.1 %>.html
```

```yaml
-  request:
      method: [GET]
      url: ^/v\d/identity/authorize
      query:
         redirect_uri: "https://(.*)/app.*"
   response:
      headers:
         location: https://<% query.redirect_uri.1 %>/auth
      status: 302
```

```yaml
-  request:
      method: [GET]
      url: ^/account/(\d{5})/category/([a-zA-Z]+)
      query:
         date: "([a-zA-Z]+)"
      headers:
         custom-header: "[0-9]+"
   response:
      status: 200
      body: Returned invoice number# <% url.1 %> in category '<% url.2 %>' on the date '<% query.date.1 %>', using header custom-header <% headers.custom-header.0 %>
```

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

### Query Parameter Matching with Literal Values

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Match query parameters with exact string values. Order of parameters does not matter.

```yaml
-  request:
      url: ^/with/parameters$
      query:
         search: search terms
         filter: month

```

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

### Stub Matching Pseudocode

Source: https://stubby4j.com/

This pseudocode outlines the logic for matching incoming requests to stubbed endpoints within StubRepository. It includes caching based on request hash code and iterating through stored endpoints to find a match.

```pseudocode
if (<incoming request>.hashCode found in <local cache>) {
    get <cached stubbed endpoint> from <local cache> by <incoming request>.hashCode
    return <cached stubbed endpoint>
} else {
    for each <stubbed endpoint> of stored endpoints {
        for each <property> of <stubbed endpoint> {
            if (<stubbed endpoint>.<property> != <incoming request>.<property>) {
                next stubbed endpoint
            }
        }
        store in <local cache> the found <stubbed endpoint> by hashCode

        return <stubbed endpoint>
    }
}
```

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

### Fallback to 'post' if 'file' not found

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

If the file specified in the 'file' property is not found, stubby4j will fall back to using the content defined in the 'post' property for matching.

```yaml
-  request:
      url: ^/match/against/file$
      file: postedData.json
      post: '{"fallback":"data"}'

```

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

### Invalid YAML Config with Includes and Stubs

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

This YAML configuration is invalid because it mixes 'includes' with direct stub definitions ('request'/'response') in the same file. stubby4j will fail to load this.

```yaml
includes:
   - service-1-stubs.yaml
   - service-2-stubs.yaml
   - service-3-stubs.yaml
     
-  request:
      method:
         -  GET
         -  POST
         -  PUT
      url: ^/resources/asn/.*

   response:
      status: 200
      body: >
         {"status": "ASN found!"}
      headers:
         content-type: application/json
```

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

### XML Regex for Request Matching

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Use escaped XML regex snippets for matching POST requests with XML content types. Note that regex special characters like '?' and '[]' must be escaped.

```yaml
- description: rule_1
  request:
    url: /some/resource/uri
    method: POST
    headers:
      content-type: application/xml
    post: >
      <\?xml version="1.0" encoding="UTF-8" standalone="yes"\?><idex:type xmlns:idex="http://idex.bbc.co.uk/v1"><idex:authority>(.*)</idex:authority><idex:name>(.*)</idex:name><idex:startsWith>(.*)</idex:startsWith></idex:type>
```

```yaml
- description: rule_1
  request:
    url: /some/resource/uri
    method: POST
    headers:
      content-type: application/xml
    post: >
      <\?xml version="1.0" encoding="UTF-8"\?>
      <person xmlns="http://www.your.example.com/xml/person">
          <VocabularyElement id="urn:epc:idpat:sgtin:(.*)">
              <attribute id="urn:epcglobal:product:drugName">(.*)</attribute>
              <attribute id="urn:epcglobal:product:manufacturer">(.*)</attribute>
              <attribute id="urn:epcglobal:product:dosageForm">(.*)</attribute>
              <attribute id="urn:epcglobal:product:strength">(.*)</attribute>
              <attribute id="urn:epcglobal:product:containerSize">(.*)</attribute>
          </VocabularyElement>
          <name>(.*)</name>
          <age>(.*)</age>
          <!--
            Hello,
               I am a multi-line XML comment
               <staticText>
                  <reportElement x="180" y="0" width="200" height="20"/>
                  <text><!\[CDATA\[(.*)\]\]></text>
                </staticText>
            -->
          <homecity xmlns="(.*)cities">
              <long>(.*)</long>
              <lat>(.*)</lat>
              <name>(.*)</name>
          </homecity>
          <one name="(.*)" id="urn:company:namespace:type:id:one">(.*)</one>
          <two id="urn:company:namespace:type:id:two" name="(.*)">(.*)</two>
          <three name="(.*)" id="urn:company:namespace:type:id:(.*)">(.*)</three>
      </person>
```

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

### Use external file for POST payload

Source: https://stubby4j.com/docs/http_endpoint_configuration_howto.html

Specify a local file path for the POST request body using the 'file' property. This takes precedence over the 'post' property if both are present. Modifications to the file will trigger a configuration reload if `--watch` is enabled.

```yaml
-  request:
      method: POST
      headers:
         content-type: application/json
      file: ../json/post.payload.json

```

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

### Update Default Proxy Config

Source: https://stubby4j.com/docs/admin_portal.html

Updates the default proxy configuration.

```APIDOC
## PUT /proxy-config/default

### Description
Updates the default proxy-config.

### Method
PUT

### Endpoint
/proxy-config/default

### Parameters
#### Request Body
- **None** (object (JSON or YAML)) - Required - See POST / PUT request body format

### Responses
#### Success Response (201)
- **text/plain;charset=UTF-8** - `Proxy config uuid#default updated successfully`

#### Error Response (400)
- **application/json** - `{"code":"400","message":"Bad Request"}`

#### Error Response (405)
- **text/html;charset=utf-8** - None

### Request Example
```bash
curl -X PUT -H "Content-Type: application/json" --data @put.json http://localhost:8889/proxy-config/default
```
```

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

### Define Websocket URL

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Specify the unique websocket URI path for a websocket configuration. The 'url' should not include the websocket context root path '/ws/'.

```yaml
- web-socket:
    url: /demo/web-socket/1
    ...
    ...

```

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

### Configure Binary Message Type with Direct Body

Source: https://stubby4j.com/docs/websockets_configuration_howto.html

Use 'message-type: binary' to send event payloads as bytes. The 'body' property directly contains the JSON payload, which will be serialized as bytes.

```yaml
- web-socket:
    ...
    ...

    on-open:
      ...
      message-type: binary
      body: >
         [{
            "name":"John",
            "email":"john@example.com"
         },{
            "name":"Jane",
            "email":"jane@example.com"
         }]
      ...


```
Tokens:
Raw