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.
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
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.
- Start Dev Proxy. Open a command prompt session. Enter
devproxy
and press Enter. - Trust certificate. Dev Proxy installs a certificate named
Dev Proxy CA
. A warning shows. SelectYes
to confirm that you want to install the certificate. Dev Proxy uses this certificate to decrypt HTTPS traffic sent from your machine. - Allow firewall access. Windows Firewall blocks the proxy. A warning shows. Select
Allow access
button to allow traffic through the firewall.
- Start Dev Proxy. Open a command prompt session. Enter
devproxy
and press Enter. - 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. - Accept incoming connections. A warning shows. Select
Allow
to confirm.
Start Dev Proxy. Open a command prompt session. Enter
devproxy
and press Enter.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.
When an ignored URL is matched to a request, Dev Proxy doesn't process the request, and so no output is displayed.
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 from50
to100
.
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 theconfigSection
property. - Further down the file, locate the
genericRandomErrorPlugin
object. Note the value of theerrorsFile
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 the429
response.
{
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.20.0/genericrandomerrorplugin.schema.json",
"errors": [
{
"request": {
"url": "https://jsonplaceholder.typicode.com/*"
},
"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.