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…
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
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).
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.
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.
This section shows some information on how to develop your own plugins for milkman
1.1 - Internal Model
Description of domain model of milkman
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
Description of how to setup your environment
for creating a new plugin, you can use following pom:
<projectxmlns="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
Description of some more advanced Features of Milkman
Description of some more advanced Features of Milkman
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:
currently, Http, Websocket, event-stream, Grpc and Gql requests are supported
environments are also imported
:exclamation: There are some conceptual differences between insomnia and milkman though:
Insomnia root-level requests are imported into a collection with the name of the workspace
Insomnia environments overload each other based on a hierarchy. this is flattened on import.
Grpc requests refere to a shared file in the workspace. This is flattened in milkman (i.e. file-content is copied to each request refering to it)
2.1 - Slack Integration
Slack-integration for milkman
Milkman supports slack-integration via a slackbot.
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 is a placeholder page that shows you how to use this template site.
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
Contains key-types for authentication, such as oauth-authentication
Contains key-types for authentication, such as oauth-authentication
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
Introduces Cql Requests to Milkman using cassandra datastax driver.
Introduces Cql Requests to Milkman using cassandra datastax driver.
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.
datacenter, required. for local installations, this should be ‘datacenter1’
username
username, optional
password
password, optional
Screenshot
Editing a secret oAuth Key (Password Grant).
Features
Execution of Requests against cassandra databases
3.3 - Milkman Commandline Interface
This is an experimental interactive command line interface for plugin.
This is an experimental interactive command line interface for plugin. After copying the content of the archive to the root directory of milkman,
you can start it by mm on terminal.
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*
Command
Alias
Description
Arguments
change-workspace
ws
Switches currently activated workspace
workspace the id of the workspace to switch to
change-collection
col
Switches currently activated collection
collection the id of the collection to switch to
execute-request
req
Executes a given request
requestish1 the id of the request to execute -l, --less outputs response into less -v, --verbose outputs all aspects
edit-request
e
Edits an aspect of a request
requestish1 the id of the request to execute aspect the aspect to edit
quit
q
Quits Application
1A requestish is [[Workspace-Id/]Collection-Id/]Request-Id (i.e. the first two are optional)
Screenshot
3.4 - Milkman Explore Plugin
JMesPath exploring for your json response.
Extends Milkman-rest with an additional response-tab that allows for application/json responses to be explored using JMesPath.
Note
requires milkman-rest plugin
Screenshot
Example of the explore plugin
3.5 - Milkman GraphQL Plugin
Allows to craft GraphQL requests.
Allows to craft GraphQL requests.
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
Grpc Plugin for communication with Grpc Servers.
Grpc Plugin for communication with Grpc Servers.
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
Allows to share requests etc via Privatebin.
Introduces Http request capabilities to milkman. Consists of serveral features that together should make milkman be usable as postman-replacement for day-to-day work.
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 Nosql Plugin
Introduces NoSql Requests to Milkman using JNoSql.
Introduces Nosql Requests to Milkman using JNoSql.
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.
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:
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.14 - Milkman Git Sync Plugin
Team Synchronization via Git
Support for Socket.IO transport
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.15 - Milkman Test Plugin
Testing of Requests
a testrunner plugin that allows to execute multiple requests in a sequence and verify their results.
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.
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.
