Write API Documentation

I’m raising this issue because its not listed in https://github.com/mitmproxy/mitmproxy/issues/2895

There is practically no API documentation. I am currently studying machine generated diagrams to try to understand how this works. Its no fun.

Somebody wrote “You can either run mitmdump as a regular process and send it a Ctrl+C when you are finished (importing mitmdump from mitmproxy.tools.main would work as well), or you instantiate your own DumpMaster and thenn call master.shutdown() when you are finished.” at https://discourse.mitmproxy.org/t/start-and-stop-mitmproxy-from-python-script/677.

The homepage boasts a screenshot showing this:

from mitmproxy import http

def request(flow: http.HTTPFlow):
    # redirect to different host
    if flow.request.pretty_host == "example.com":
        flow.request.host = "mitmproxy.org"
    # answer from proxy
    elif flow.request.path.endswith("/brew"):
    	flow.response = http.HTTPResponse.make(
            418, b"I'm a teapot",
        )`

Its not much to go on.

[SamJoan]

I asked on slack and was told the docs will hit stable soon, in the meantime they can be accessed at https://docs.mitmproxy.org/dev/api/mitmproxy/http.html

[Kriechi]

What you are looking for is listed as Addon development docs, mentioning hot reload and testing. Yes, we are lacking decent docs!

Let me give you a few pointers that might help you: Generally speaking, in most cases you want to write an “addon”. https://docs.mitmproxy.org/stable/addons-overview/

This is what we provide as a single script to start with mitmproxy (or mitmdump), and it can react to certain events in the lifecycle of your traffic going through the proxy. https://docs.mitmproxy.org/stable/addons-events/ https://docs.mitmproxy.org/stable/addons-scripting/

Also, take a look at our examples folder (matching your mitmproxy release!).