Documentation

• 1: Milkman Plugin Development
• 1.1: Internal Model
• 1.2: Development Setup
• 2: Advanced Features
• 2.1: Slack Integration
• 3: Milkman Plugins
• 3.1: Milkman Auth Plugin
• 3.2: Milkman Cassandra Plugin
• 3.3: Milkman Commandline Interface
• 3.4: Milkman Explore Plugin
• 3.5: Milkman GraphQL Plugin
• 3.6: Milkman Grpc Plugin
• 3.7: Milkman Http Plugin
• 3.8: Milkman Note Plugin
• 3.9: Milkman Privatebin Plugin
• 3.10: Milkman Scripting Plugin
• 3.11: Milkman Socket.IO Plugin
• 3.12: Milkman Jdbc Plugin
• 3.13: Milkman Git Sync Plugin
• 3.14: Milkman Test Plugin
• 3.15: Milkman Websocket Plugin

Milkman - An Extensible Request/Response Workbench

Milkman is heavily inspired by Postman. But I got sick of all those electron-based applications that need ages and loads of memory to start up. Therefore i created a JavaFx-based workbench for crafting requests / responses. It is not limited to e.g. http (or more specifically rest) requests. Due to nearly everything being a plugin, other things are possible, like database-requests or GRPC, GraphQl, etc…

Download

• Download latest version in Release Section. Or download Nightly version for latest changes.
• Download plugin archive as well, if you want to use any of those plugins.
• unzip everything into the same directory and start application via either the supplied start-scripts or milkman.exe

Install via Chocolatey (Win)

• To install just Milkman run Choco install milkman
• To install a plugin run Choco install milkman-<plugin name> ex. Choco install milkman-explore
• Install Milkman and all plugins available run Choco install milkman-plugins
• Milkman will be installed under C:\tools\milkman.

Install via Homebrew (MacOs)

• To install, run brew install --cask milkman. All plugins are included.
• To update, run brew upgrade --cask

Changes

latest changes can be seen in the Changelog

FAQ

some resolved issues and FAQs are available in the wiki. If you have any questions, create a new Issue or ask in Discussions.

Features

• Everything is a plugin: Request-types (e.g. Http Request), request-aspects (e.g. Headers, Body, etc), editors for request aspects (e.g. table-based editors for headers), importers, whatever it is, you can extend it. The core application only handles Workspaces with Environments, Collections, Requests and their aspects.
• Http Request Plugin: Several plugins are provided already that extend the core application to be a replacement for postman. Crafting and Executing Http/Rest requests with json highlighting. Support Proxy-server configuration and SSE.
• Grpc Plugin: support of Grpc Services, Server Reflection and Streaming
• Test Runner: run several requests as separate test-scenario
• JavaFX Application: as in: fast (compared to electron at least :D) and skinn-able (you can extend milkman with your own themes using simple CSS).
• Commandline Interface: there is a command line interface for Milkman which allows to edit/execute requests on your command line.
• Slack Command: you can use /milkman <privatebin-url> in slack to share requests in a better way. More Info.
• Some more details of the core application features, such as hotkeys etc.

Existing Plugins:

Note: see respective plugin folder for more details

Http Request Plugin: (included in main distribution)

The Http request plugin packaged with the release contains all means to do http request as well as import collections, environments or dumps from postman. To migrate from postman, just export a dump-file from postman and import it by pasting its content into the Postman (v2.1) Dump-Importer. The Http Request Plugin also comes with Proxy-support. Some proxies require credentials and support for supplying BASIC proxy credentials is built into the plugin. See Options-page to activate that as it is off by default. Additionally, the plugin supports chunked responses, enabling testing of Server-sent events (SSE).

Graphql Plugin

Simple Graphql Plugin to craft GraphQL requests. No Auto-complete or schema valiadtion included.

Grpc Plugin

Grpc plugin with server-reflection support and streaming-support. Can also query via proto-defintion.

JDBC Plugin

This plugin introduces SQL capability to milkman. You can query SQL databases via milkman as well, using JDBC drivers.

Cassandra Plugin:

Allows to execute CQL queries for given cassandra databases.

Git Team Synchronization Plugin

This plugin allows to synchronize workspaces via Git (using Differential Synchronization). Teams can use this plugin to have a shared workspace that synchronizes between members.

Explore Plugin:

This plugin extends Rest-responses by adding an Explore-Tab where you can use JMesPath queries against a JSON response.

Scripting Plugin:

Extends requests by executing a script after request execution. This allows to e.g. set environment variables based on results of json.

PrivateBin Sharing Plugin

Adds capability to share requests via PrivateBin, including Burn After Reading feature

Note Plugin:

This is a sample plugin that allows to add arbitrary description to every request. Serves as a starting point for learning to extend milkman.

Test Plugin

A testrunner plugin that allows to run multiple requests in sequence and verify the results

Auth Plugin

An OAuth Plugin for managing oauth credentials and transparent refreshing of tokens

Websocket Plugin

A websocket plugin for interacting with websocket endpoints

Socket.IO Plugin

A Socket.IO plugin for interacting with Socket.IO endpoints

Showcase

Screenshot of Milkman light theme

Screenshot of Milkman Dark theme with horizontal layout

Plugins

No client fits all, so you are encouraged to write your own plugins to e.g. add headers that are necessary for your internal service structures or add importers for internal service registries.

A sample plugin was provided that extends all requests with a Note tab so you can add some description to any kind of requests.

More details about developing plugins can be found in the plugin development guide.

Installation: all plugins are to be copied to the /plugins folder

Changes

latest changes can be seen in the Changelog

1 - Milkman Plugin Development

1.1 - Internal Model

Plugins in milkman can extend various functionality. For this, an explanation of how a request is structured is necessary first.

Getting Started

A sample plugin was created that shows how to add an Aspect Tab to a Request.

if you want to setup a new project, an exemplary pom can be found here.

Data Model

The core of milkman is very abstract and is only intended to organize workspaces, which contain environments and collections of requests. A request is of a specific type and might contain some basic data. In the case of an HttpRequest, this might be the URL and the Method.

A request can also contain several RequestAspects which describe the request object further. In our example, this might be headers or the body of a request, but can also contain totally unrelated and auxiliary attributes.

All Aspects and the container gets serialized using Jackson and stored in a local Database.

Extension Points

Milkman uses SPI for extension. You just have to provide an implementation to one of the Extension Points below and move your packaged jar into the /plugin folder to have milkman pick up your plugin.

RequestAspectsPlugin

A request aspect can add aspects to either a request- or response container as well as according editors (providing the Tab to edit this specific aspect).

ContentTypePlugin

A content type plugin is used to format and highlight content based on a mime-type.

RequestTypePlugin

A plugin providing a request type such as HttpRequest, or SQL request or whatever you can think of. This plugin has to provide a small editor for basic attributes of the request as well.

ImporterPlugin

a plugin that imports things into the current workspace, such as collections, requests, environments.

OptionPageProvider

a plugin to provide a UI for editing options of a “logical” plugin. The OptionPageBuilder can be used to create common ui. On startup, changed options will be loaded from database.

UI Theme Plugin

provides an application-theme css and a syntax-theme css for styling.

Workspace Synchronizer Plugin

provides a mechanism to synchronize the workspace with some external mechanism

Request Export Plugin

extension point for adding export methods to a request-type.

Collection Export Plugin

extension point for adding export methods to a collection.

Persistence

All requests and RequestAspects (not response-aspects) will be stored in database and serialized using jackson. So you have to make sure that your classes properly serialize/deserialize.

Common Components

Some common components are provided by milkman to make development of plugins easier:

• TableEditor: a table that might or might not be editable. used for editing headers or environments or such.
• ContentEditor: a content editor that supports highlighting and formatting
• Dialogs: some common dialogs, such as credentialsInput or StringInput.

Testing

milkman uses TestFX for testing. A sample test can be seen in the notes plugin.

Gotchas

JavaFX uses a lot of weak references. That means, if you don’t keep references to e.g. bindings or controllers even (if they are not referred to by e.g. FXML-onActions), they get garbage-collected and the bindings simply don’t work. You can use setUserData in some cases to have a strong reference of the UI element to e.g. the controller, so they both get garbage-collected at the same time.

1.2 - Development Setup

for creating a new plugin, you can use following pom:

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	
	<groupId>...</groupId>
	<artifactId>...</artifactId>
	<version>...</version>
	
	
	<dependencies>
		<dependency>
			<groupId>com.github.warmuuh.milkman</groupId>
			<artifactId>milkman</artifactId>
			<version>...</version>
			<scope>provided</scope>
		</dependency>
		<!-- and for refering to plugins of milkman: -->
		<dependency> 
			<groupId>com.github.warmuuh.milkman</groupId> 
			<artifactId>milkman-rest</artifactId> 
			<version>...</version> 
			<scope>provided</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<!-- for packaging all your dependencies into one jar, excluding provided ones -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-assembly-plugin</artifactId>
				<version>2.6</version>
				<configuration>
					<descriptorRefs>
						<descriptorRef>jar-with-dependencies</descriptorRef>
					</descriptorRefs>
					<appendAssemblyId>false</appendAssemblyId>
				</configuration>
				<executions>
					<execution>
						<id>assemble-all</id>
						<phase>package</phase>
						<goals>
							<goal>single</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
	
	
	<repositories>
		<repository>
			<id>jitpack.io</id>
			<url>https://jitpack.io</url>
		</repository>
	</repositories>

</project>

2 - Advanced Features

Code Folding

• Folding is supported in response body area
• Toolbar actions: expand all, collapse all, expand one level, collapse one level
• Clicking on the line-symbol expands the node
• Right-Clicking on the line-symbol expands the whole subtree

Hotkeys

• CTRL+ENTER - Execute Request
• CTRL+N - New Request
• CTRL+R - Rename Active Request
• CTRL+W - Close Active Request
• CTRL+S - Save Active Request
• CTRL+E - Edit current Environment
• CTRL+Space - Quick-Edit of Variables
• ESC - Cancel running Request

Copy&Paste in Tables

• You can CTRL+C selected rows to copy its value
• You can CTRL+V multiple rows into a table

Quick Edit for Variables

• You can highlight variables.
• Clicking on it opens popup for modification/creation
• ESC hides highlighting

Keys

• secret keys that should not be exported or synced can be setup using the key-symbol
• currently, secret keys are only plain type keys, but will be e.g. oauth-keys etc
• can be accessed using {{key:name-of-key}} variable

Libraries

you can register libraries to easily look-up and import services from a central registry, such as APIs.guru.

Code Templates

• you can define custom templates for every type of request yourself. Do you often need to write Spring Webclient code? setup some custom template for it. (you can do so in the options dialog)
• Some predefined templates are available already. (see here)
• Syntax is similar to mustache but enhanced with whitespace control. example:

curl -X {{httpMethod}}  

{{_#headers.entries-}}
-H "{{name}}: {{value}}"
{{-/headers.entries_}}

{{url}}

• Whitespace control:
  • {{- removes all whitespaces (including linebreaks) before the tag
  • {{_ removes all whitespaces (including linebreaks) before the tag and replaces it with one space
  • -}} removes all whitespaces (including linebreaks) after the tag
  • _}} removes all whitespaces (including linebreaks) after the tag and replaces it with one space

2.1 - Slack Integration

You can either host it yourself or use the heroku-hosted instance:

Usage

Once added to your workspace, you can share a private-bin export url via:

/milkman <privatebin-url>

Features

It will nicely render the shared request and offers several ways for viewers to use the request, such as viewing the request as curl-command or http-request.

Preview of a request in slack

and users can choose how to view the request:

Quick-export of a request directly in slack.

it also supports all other request types, such as gRPC:

Example of a Grpc request in slack

Planned

More features are planned, such as:

• execution of requests on backend
• support for burn-after-reading in privatebin
• more templates

3 - Milkman Plugins

This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project.

3.1 - Milkman Auth Plugin

Features

• supports oauth2
  • password-grant, client-credential grant and authorization-code grant

Screenshot

Editing a secret oAuth Key (Password Grant).

Remarks

• does not yet support specifying a redirect-url for authorization-code as there is currently no browser included.

3.2 - Milkman Cassandra Plugin

Requirements

This plugin requires milkman-jdbc plugin

Installation

After placing the jar into \plugin folder, you also have to place the driver-jars you want to use in that folder as well.

Usage

The used url is of following format:

cql://host[/keyspace]?dc=...[&username=...&password=...]

supported parameters

Screenshot

Editing a secret oAuth Key (Password Grant).

Features

• Execution of Requests against cassandra databases

3.3 - Milkman Commandline Interface

Screenshot

Features

• Editing Request-Aspects via nano
• Executing requests
• Analyzing responses via less
• Interactive mode (entered by simply starting mm) or non-interactive mode (by executing commands via mm [command])
• Tab-Completion on interactive mode

Commands

• Note: all IDs are derived from the original names. All lowercase and special characters are replaced with -. E.g. Your Workspace becomes your-workspace*

¹A requestish is [[Workspace-Id/]Collection-Id/]Request-Id (i.e. the first two are optional)

Screenshot

3.4 - Milkman Explore Plugin

Note

• requires milkman-rest plugin

Screenshot

Example of the explore plugin

3.5 - Milkman GraphQL Plugin

Note

• This plugin is rather simple and does not include advanced features such as auto-completion or schema-validation (yet).
• Requires milkman-rest plugin

Screenshot

Example of the GraphQl plugin

3.6 - Milkman Grpc Plugin

Features

• Can work with Server Reflection to query services and retrieve *.proto files
• Given a *.proto file, Server Reflection is not necessary to query a service
• Read/write ASCII headers
• Support Server/client/both streams

Screenshot

Example of the Grpc plugin

Example of Server streaming

Client Streaming

To send multiple messages, just add multiple json objects to the payload, divided by two new lines.

3.7 - Milkman Http Plugin

Screenshot

Example of the Rest plugin

Example of Server Sent Events Streaming

Features

• Postman-like UI
• Crafting of requests by editing body, headers, parameters
• Highlighting/formatting for json
• Proxy-Authentication support (BASIC for now)
• Importers for Postman exports (Collections, Environments, Data-Dump)
• Importers for OpenApi v3.0
• (planned) Exporters
• Support import of APIs listed at APIs.guru, see demo

3.8 - Milkman Note Plugin

This plugin serves demonstrational purposes and should show how milkman can be extended.

Screenshot

Example of the Notes plugin

3.9 - Milkman Privatebin Plugin

Screenshot

Example of the Privatebin plugin

Features

• Customizable Privatebin installation
• Client-side AES encryption
• Share requests via simple URL
• Burn After Reading feature

3.10 - Milkman Scripting Plugin

Features

• Provides possibility to pre-load scripts from web, such as chai, via settings.
• Pre-Request script execution before actual request is made
• Post-Request script execution with logging output
• Extensions of template parameters with js: prefix
  • For example, you can set BASIC authorization via header:
    Authorization: Basic {{js:base64("username:password")}}

Example for scripts

var url = JSON.parse(milkman.response.body.body).url
milkman.setEnvironmentVariable("test.url", url)

example of pre-script:

var headerVal = milkman.request.headers.entries[0].value
milkman.toast(headerVal)

example of chai script (if you include chai in preload scripts):

chai.should();
var body = JSON.parse(mm.response.body.body)
body.should.have.lengthOf(200);

Screenshot

Example of the Scripting plugin

Preferences:

Example of the Scripting plugin

API

milkman (aliased to mm) is the only object available. It provides following properties:

• request: an accessor for request-aspects. Every property of this request-object tries to fetch an according aspect. E.g. request.body would be the body-aspect of the request-container. (Thats why you have to write request.body.body, because the body-aspect stores its content in the body variable as well. Might be streamlined in the future)
• response: an accessor for response-aspects. Every property of this response-object tries to fetch an according aspect. E.g. response.body would be the body-aspect of the response-container. (Thats why you have to write response.body.body, because the body-aspect stores its content in the body variable as well. Might be streamlined in the future)
• setEnvironmentVariable(String, String) sets an environment variable in the currently active environment (if there is any activated).
• toast(String) shows a toast at the bottom of the window

console works as usual as well

besides that, some often used functions are available:

• base64(string), sha1(string), sha256(string), sha512(string)

3.11 - Milkman Socket.IO Plugin

Features

• supports Socket.IO

Screenshot

Example of the Socket.IO plugin

Note

• requires milkman-rest plugin

3.12 - Milkman Jdbc Plugin

Installation

After placing the jar into \plugin folder, you also have to place the driver-jars you want to use in that folder as well.

Screenshot

Example of the Sql plugin

Features

• Execution of Requests against Jdbc compatible Databases.
• (planned) exploration of table structures / existing tables.

3.13 - Milkman Git Sync Plugin

This plugin allows to setup a git repository to where a workspace can be synchronized. Synchronization works by computing the diffs and applying them in a fuzzy manner to the latest version (simple algorithm of Differential Synchronization).

Screenshot

Example of the Scripting plugin

Features

• synchronizes (on-demand for now) workspaces with a remote git repository

Remark

• This feature is experimental.

3.14 - Milkman Test Plugin

Usage

Just Drag-and-drop requests you want to execute into the test-tab and you are ready to go.

Demo

Environment

On execution, a separate environment only for this test-run will be created, so everything written to the current environment. For differentiation in scripts, a __TEST__ = true variable is also added to the current environment.

Example test that is only executed on test-runs:

if (mm.getEnvironmentVariable("__TEST__")){
  chai.should();
  var json = JSON.parse(mm.response.body.body)
  json.should.have.property('name').that.is.equal("Leanne Graham")
}

Remark

This plugin is still in early development, so it might not seem to contain a lot of features. They will be added on-the-go when the need / issue arises.

3.15 - Milkman Websocket Plugin

Features

• supports ws and wss
• can interactively send messages

Screenshot

Note

• requires milkman-rest plugin