Get started with Dev Proxy

Dev Proxy is a command line tool that helps you simulate behaviors and errors of cloud APIs to help you build resilient apps.

In this tutorial, you learn how to install, run, and configure Dev Proxy.

If you do run into any difficulties, don’t hesitate to contact us by raising a new issue and we're glad to help you out.

Install Dev Proxy

The easiest way to install Dev Proxy is by using winget. Alternatively, you can install Dev Proxy manually.

To install Dev Proxy using winget, run the following command:

winget install Microsoft.DevProxy --silent

Important

Dev Proxy installer adds a new entry to PATH. To use Dev Proxy after installation, you must restart the command prompt to ensure that the PATH environment variables have refreshed.

Note

To try the latest preview features, install the beta version of Dev Proxy.

To install Dev Proxy using winget, run the following command:

winget install Microsoft.DevProxy.Beta --silent

To run the beta version of Dev Proxy use devproxy-beta

The easiest way to install Dev Proxy is by using Homebrew. Alternatively, you can install Dev Proxy manually.

To install Dev Proxy using Homebrew, run the following commands:

brew tap microsoft/dev-proxy
brew install dev-proxy

Note

To try the latest preview features, install the beta version of Dev Proxy.

To install Dev Proxy using Homebrew, run the following commands:

brew tap microsoft/dev-proxy
brew install dev-proxy-beta

To run the beta version of Dev Proxy use devproxy-beta

The easiest way to install Dev Proxy is by using the setup script. Alternatively, you can install Dev Proxy manually.

To install Dev Proxy using the setup script, run the following commands:

bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

If you use PowerShell, run the following command:

(Invoke-WebRequest https://aka.ms/devproxy/setup.ps1).Content | Invoke-Expression

Note

To try the latest preview features, install the beta version of Dev Proxy.

To install Dev Proxy using the setup script, run the following commands:

bash -c "$(curl -sL https://aka.ms/devproxy/setup-beta.sh)"

If you use PowerShell, run the following command:

(Invoke-WebRequest https://aka.ms/devproxy/setup-beta.ps1).Content | Invoke-Expression

To run the beta version of Dev Proxy use devproxy-beta

Start Dev Proxy for the first time

The first time you start Dev Proxy on your machine there are a few steps to follow to ensure that Dev Proxy can intercept requests from your machine and respond successfully. You won't have to repeat these steps after the first run.

  1. Start Dev Proxy. Open a command prompt session. Enter devproxy and press Enter.
  2. Trust certificate. Dev Proxy installs a certificate named Dev Proxy CA. A warning shows. Select Yes to confirm that you want to install the certificate. Dev Proxy uses this certificate to decrypt HTTPS traffic sent from your machine.
  3. Allow firewall access. Windows Firewall blocks the proxy. A warning shows. Select Allow access button to allow traffic through the firewall.
  1. Start Dev Proxy. Open a command prompt session. Enter devproxy and press Enter.
  2. Trust certificate. Dev Proxy installs a certificate named Dev Proxy CA, which it uses to decrypt HTTPS traffic sent from your machine. A warning shows. Press y to confirm that you want to trust the certificate.
  3. Accept incoming connections. A warning shows. Select Allow to confirm.
  1. Start Dev Proxy. Open a command prompt session. Enter devproxy and press Enter.

  2. Trust certificate. Dev Proxy uses a custom SSL certificate to decrypt HTTPS traffic sent from your machine.

    Important

    The following instructions are for Ubuntu. For other Linux distributions, the steps might differ.

    To install and trust the certificate, in a new command prompt, run the following commands:

    # Export Dev Proxy root certificate
    openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
    # Install the certificate
    sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
    # Update certificates
    sudo update-ca-certificates
    

The command prompt displays the following output:

 info    8 error responses loaded from devproxy-errors.json
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

By default, Dev Proxy is configured to:

  • Intercept requests made to any JSON Placeholder API endpoint
  • Simulate API error responses and API throttling with a failure rate of 50%

Intercept requests

Dev Proxy will intercept requests made to known URLs from any application on your machine. When a request is detected, Dev Proxy passes the request through to the API (take no action), or return a response.

  • Send a request to the JSON Placeholder API from the command line and switch back to the proxy process to view the output.

In PowerShell, use the Invoke-WebRequest cmdlet to send a GET request to the JSON Placeholder API.

Invoke-WebRequest -Uri https://jsonplaceholder.typicode.com/posts

If you use curl, send a GET request to the JSON Placeholder API using the following command.

curl -ix http://localhost:8000 https://jsonplaceholder.typicode.com/posts

You can also use an API client like Postman to send a GET request to https://jsonplaceholder.typicode.com/posts.

An entry is shown with some basic information about the incoming request and the action that Dev Proxy performed. Dev Proxy simulates an error response with a 50% chance. If your request doesn't return an error, Dev Proxy passes it through.

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through
  • Repeat sending requests to the JSON Placeholder API from the command line, until an error response is returned.
 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 oops  ╰ 403 Forbidden

When Dev Proxy returns an error response, a chaos label is displayed in the entry.

  • Try sending requests to other endpoints available on the JSON Placeholder API
    • https://jsonplaceholder.typicode.com/posts
    • https://jsonplaceholder.typicode.com/posts/1
    • https://jsonplaceholder.typicode.com/posts/1/comments
    • https://jsonplaceholder.typicode.com/comments?postId=1

Stop Dev Proxy safely

When you no longer require Dev Proxy to be running, you should always stop it safely.

  • Press Ctrl + C to safely stop Dev Proxy.

If you shut down the command prompt session, Dev Proxy doesn't unregister correctly as the system proxy, and you might experience some common problems.

Update the URLs to watch

By default, Dev Proxy is configured to intercept any request made to the JSON Placeholder API. You can configure Dev Proxy to intercept requests to any HTTP API.

  • In a command prompt, run brew list dev-proxy to locate the installation folder.
  • Open the Dev Proxy installation folder in Finder.
  • In the Dev Proxy installation folder, open devproxyrc.json in a text editor.
  • Locate the urlsToWatch array.
"urlsToWatch": [
  "https://jsonplaceholder.typicode.com/*"
],

The urlsToWatch array represents the known URLs. Dev Proxy watches requests from the current entry to any endpoint. The entry uses an asterisk after the URL as a wildcard. Adding more entries into this array expands the URLs that Dev Proxy watches out for.

Let's consider that you don't want Dev Proxy to intercept requests made to a specific endpoint.

  • Add a new entry to the urlsToWatch array.
"urlsToWatch": [
  "!https://jsonplaceholder.typicode.com/posts/2",
  "https://jsonplaceholder.typicode.com/*"
],

The exclamation mark at the beginning of the URL tells Dev Proxy to ignore any requests that match that URL. You can mix and match exclamation marks and asterisks in a URL.

  • At the command line, enter devproxy and press Enter to start Dev Proxy.
  • Send a request to https://jsonplaceholder.typicode.com/posts/2 from the command line and view the output.

An entry is shown confirming that the request was ignored and passed through to the API.

 req   ╭ GET https://jsonplaceholder.typicode.com/posts/2
 api   ╰ Passed through

The order in which the URLs are listed in the urlsToWatch array is important. Dev Proxy processes these URLs in order. When a URL matches, it isn’t processed again. Therefore, placing the URL first ensures that the request is ignored before the next URL is processed.

Change failure rate

By default, Dev Proxy is configured to fail requests with a 50% chance to URLs that are being watched. You can increase or decrease the chance of a request returning an error response.

Let’s update the failure rate so that every request to the JSON Placeholder API returns an error response.

  • In the Dev Proxy installation folder, open devproxyrc.json in a text editor.
  • Locate the rate property and update the value from 50 to 100.

The devproxyrc.json file contains configuration settings that are used when you start Dev Proxy. When changing configuration settings, you should always stop and start Dev Proxy for the changes to be persisted.

  • At the command line, enter devproxy and press Enter to start Dev Proxy.
  • Send a request to the JSON Placeholder API from the command line and view the output.

Alternatively, you can override configuration settings at runtime by using the --failure-rate option when starting Dev Proxy.

devproxy --failure-rate 100
  • Press Ctrl + C to safely stop Dev Proxy.

Simulate throttling

By default, Dev Proxy returns a range of generic 400 and 500 error responses. You can customize these error responses to your own needs.

Dev Proxy uses plugins to enable different API behaviors, by default, we enable two plugins for you.

  • GenericRandomErrorPlugin plugin provides the ability for Dev Proxy to respond with an error response.
  • RetryAfterPlugin plugin provides the ability for Dev Proxy to inject a dynamic value into the Retry-After header in the error response.

Let’s change the configuration so that Dev Proxy always returns a 429 Too Many requests error response to simulate throttling.

First let's locate the location of the file that contains the error definitions.

  • In the Dev Proxy installation folder, open devproxyrc.json in a text editor.
  • In the plugins array, locate the entry for the GenericRandomErrorPlugin plugin. Note the value of the configSection property.
  • Further down the file, locate the genericRandomErrorPlugin object. Note the value of the errorsFile property.

Tip

The location of the errors file is also displayed in the output when you start Dev Proxy.

  • In the Dev Proxy installation folder, open devproxy-errors.json in a text editor.
  • Remove all response entries in the responses array, except for the 429 response.
{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.18.0/genericrandomerrorplugin.schema.json",
  "responses": [
    {
      "statusCode": 429,
      "body": {
        "message": "Too Many Requests",
        "details": "The user has sent too many requests in a given amount of time (\"rate limiting\")."
      },
      "headers": {
        "Retry-After": "@dynamic"
      }
    }
  ]
}
  • At the command line, enter devproxy and press Enter to start Dev Proxy.
  • Send a request to the JSON Placeholder API from the command line and view the output.
 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 oops  ╰ 429 TooManyRequests
  • Press Ctrl + C to safely stop Dev Proxy.

Next step

Learn how to use Dev Proxy to simulate random errors for your own application.