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

winget install Microsoft.DevProxy --silent

winget install Microsoft.DevProxy.Beta --silent

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

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

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

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

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

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

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.

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 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.

• 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.