stubby4j

Back to Home

stubby4j Admin Portal

Table of contents

• The admin portal
• The status page
• Available REST API summary
  • Creating new/overwriting existing stubs & proxy configs
  • Listing existing stubs & proxy configs as YAML string
  • Updating existing stubs & proxy configs
  • Deleting existing stubs & proxy configs
  • POST / PUT request body format
• Client programmatic API

The admin portal

Upon starting the stubby4j service, the admin portal runs on <host>:<admin_port> (e.g.: localhost:8889) or wherever you described through stubby’s command line args.

The admin portal provides a web UI page (i.e.: status page) to view the stubbed data. In addition, the admin portal exposes a set of RESTful(ish) APIs that enable management of loaded in-memory stubs & proxy configs, which were loaded from the YAML config provided to stubby4j during start-up.

The status page

You can view the configured stubs & proxy configs by navigating to <host>:<admin_port>/status from your browser

Available REST API summary

CAVEATS

• Stubs can be updated/deleted by either:
  • stub_numeric_id. The specific stub stub_numeric_id (resource-id-<id>) can be found when viewing stubs’ YAML at <admin_portal_host>:<port>/status. Please note, deleting stubs by stub_numeric_id can get rather brittle when dealing with big or/and shared YAML configs. Therefore it is better to configure uuid property per stub in order to make the stub management easier & isolated.
  • unique identifier (See “HTTP endpoint configuration HOWTO” section)
• When defining only one proxy config (e.g.: a catch-all for all stubs), it must be configured without a uuid OR have a uuid with a value default
• The default proxy config cannot be deleted via the DELETE REST API
• Proxy configs can only be updated by a unique identifier, uuid
• The default proxy config can be updated via the PUT REST API even if uuid has not been explicilty defined (it will be defined impliclty).
• When updating stubs via PUT API, you can update only one stub at the time, i.e.: bulk updates are not supported yet.

Creating new/overwriting existing stubs & proxy configs

Listing existing stubs & proxy configs as YAML string

Updating existing stubs & proxy configs

Deleting existing stubs & proxy configs

POST / PUT request body format

To manage the stubbed data via the POST/PUT API, structure the request payload as either a JSON array or YAML list (-) syntax.

JSON support

JSON is a subset of YAML 1.2, SnakeYAML that stubby4j leverages for YAML & JSON parsing implements YAML 1.1 (https://yaml.org/spec/1.1/)

POST / PUT JSON payload examples

Single stub payload

[
  {
    "request": {
      "url": "^/resources/something/new",
      "query": {
        "someKey": "someValue"
      },
      "method": [
        "GET"
      ]
    },
    "response": {
      "body": "OK",
      "headers": {
        "content-type": "application/xml"
      },
      "status": 201
    }
  }
]

Multiple stub payload

[
  { 
    "description": "this is a feature describing something",
    "request": {
      "url": "^/path/to/something$",
      "post": "this is some post data in textual format",
      "headers": {
         "authorization-basic": "bob:password"
      },
      "method": "POST"
    },
    "response": {
      "status": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "latency": 1000,
      "body": "Your request was successfully processed!"
    }
  },
  {
    "request": {
      "url": "^/path/to/anotherThing",
      "query": {
         "a": "anything",
         "b": "more"
      },
      "headers": {
        "Content-Type": "application/json"
      },
      "method": "GET"
    },
    "response": {
      "status": 204,
      "headers": {
        "Content-Type": "application/json",
        "Access-Control-Allow-Origin": "*"
      },
      "file": "path/to/page.html"
    }
  },
  {
    "request": {
      "url": "^/path/to/thing$",
      "headers": {
        "Content-Type": "application/json"
      },
      "post": "this is some post data in textual format",
      "method": "POST"
    },
    "response": {
      "status": 304,
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
]

Single stub with multiple proxy configs payload

[
  {
    "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"
      }
    }
  }
]

Client programmatic API

You can manage stubby4j loaded config with the help of StubbyClient.

stubby4j has a class YamlBuilder, a builder, that enables to build a YAML string, which can be used as a POST/PUT payload (alternatively, you can always load your payload content from a local file as a resource when making requests). You can then make a requests to the admin portal using StubbyClient to manage the stubs programamtically.

There is a test that demonstrates the usage of the YamlBuilder and StubbyClient#updateStubbedData(…) when updating proxy-config configuration by uuid.

Although the aforementioned test is about managing an existing proxy-config definition, the same builder can be used for building request payloads to create/update stub request with its response.

Back to Home