move docs to the microsite

docs/plugins/call-existing-api.md

@@ -71,11 +71,7 @@ Example:
 ```yaml
 # In app-config.yaml
 proxy:
-  '/frobs':
-    target: 'http://api.frobsco.com/v1'
-    changeOrigin: true
-    pathRewrite:
-      '^/proxy/frobs/': '/'
+  '/frobs': http://api.frobsco.com/v1
 ```
 
 ```ts
@@ -86,9 +82,8 @@ fetch(`${backendUrl}/proxy/frobs/list`)
   .then(payload => setFrobs(payload as Frob[]));
 ```
 
-The proxy is powered by the `http-proxy-middleware` package, and supports all of
-its
-[configuration options](https://github.com/chimurai/http-proxy-middleware#options).
+The proxy is powered by the `http-proxy-middleware` package. See
+[Proxying](proxying.md) for a full description of its configuration options.
 
 Internally at Spotify, the proxy option has been the overwhelmingly most popular
 choice for plugin makers. Since we have DNS based service discovery in place and

docs/plugins/proxying.md

@@ -3,4 +3,73 @@ id: proxying
 title: Proxying
 ---
 
-## TODO
+## Overview
+
+The Backstage backend comes packaged with a basic HTTP proxy, that can aid in
+reaching backend service APIs from frontend plugin code. See
+[Call Existing API](call-existing-api.md) for a description of when the proxy
+can be the best choice for communicating with an API.
+
+## Getting Started
+
+The plugin is already added to a default Backstage project.
+
+In `packages/backend/src/index.ts`:
+
+```ts
+const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
+
+const service = createServiceBuilder(module)
+  .loadConfig(configReader)
+  /** ... other routers ... */
+  .addRouter('/proxy', await proxy(proxyEnv, '/proxy'));
+```
+
+## Configuration
+
+Configuration for the proxy plugin lives under a `proxy` root key of your
+`app-config.yaml` file.
+
+Example:
+
+```yaml
+# in app-config.yaml
+proxy:
+  '/simple-example': http://simple.example.com:8080
+  '/larger-example/v1':
+    target: http://larger.example.com:8080/svc.v1
+    headers:
+      Authorization:
+        $secret:
+          env: EXAMPLE_AUTH_HEADER
+```
+
+Each key under the proxy configuration entry is a route to match, below the
+prefix that the proxy plugin is mounted on. It must start with a slash. For
+example, if the backend mounts the proxy plugin as `/proxy`, the above
+configuration will lead to the proxy acting on backend requests to
+`/proxy/simple-example/...` and `/proxy/larger-example/v1/...`.
+
+The value inside each route is either a simple URL string, or an object on the
+format accepted by
+[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
+
+If the value is a string, it is assumed to correspond to:
+
+```yaml
+target: <the string>
+changeOrigin: true
+pathRewrite:
+  '^<url prefix><the string>/': '/'
+```
+
+When the target is an object, it is given verbatim to `http-proxy-middleware`
+except with the following caveats for convenience:
+
+- If `changeOrigin` is not specified, it is set to `true`. This is the most
+  commonly useful value.
+- If `pathRewrite` is not specified, it is set to a single rewrite that removes
+  the entire prefix and route. In the above example, a rewrite of
+  `'^/proxy/larger-example/v1/': '/'` is added. That means that a request to
+  `/proxy/larger-example/v1/some/path` will be translated to a request to
+  `http://larger.example.com:8080/svc.v1/some/path`.