What Is Microsoft Graph Developer Proxy?

Overview

Microsoft Graph Developer proxy is a tool that helps to simulate elusive API errors that might typically occur in specific circumstances (e.g: in the Production environment). It helps you build logic into your code to handle these errors during development. It is not uncommon for errors to occur arbitrarily in the production environment and to be difficult to detect during the development process due to environment-dependent factors. These errors typically occur when the application is used at scale or occurs in specific circumstances. By using the Microsoft Graph Developer proxy, you can simulate these errors and verify that your application handles them gracefully if they occur. Providing best practices and help creating highly resilient applications is the aim of the tool.

Consider the following scenario, a time-sensitive enterprise application is built using API integration. Before it is approved for PROD deployment, it is thoroughly tested by developers and also tested with pilot users. However, when it is deployed to PROD users report the issue and they receive the generic exception message “System encountered an issue” or “Error Occurred”. Due to the time-sensitive nature of the application, this can create chaos as the user is unable to comprehend what is going on.

Upon investigation, it is found that this issue occurs when the API returns HTTP error 429 which was not reproducible in the dev environment. Microsoft Graph developer proxy is useful in these cases where you can simulate the API errors in the dev environment and address these errors by handling exceptions gracefully. Furthermore, it allows users(developers) to mock API responses to ensure that the response can be handled appropriately in the integrated application.

Advantages of Microsoft Graph Developer Proxy

• Operating System agnostic (you can run it on Windows, Mac or Linux)
• It allows developers to test their code against the APIs by simulating errors.
• By intercepting HTTP requests with mock responses, it is easier to test API-related code and handle exceptions properly.
• Provide API guidance and best practices recommendation, e.g.: notifications of request to Microsoft Graph beta API, using $select parameter etc.
• Developers can control proxy settings by using parameters, such as throttling rate, port, and HTTP error messages.
• Support for recording request logs and analyze in the context of other requests.

Prerequisites for using Microsoft Graph Developer Proxy

To use the Microsoft Graph Developer Proxy, you'll need to have the following prerequisites,

• Download the ZIP file for your operating system.
• Extract the contents of the ZIP into a folder.

Once you have these downloaded, you can use the following steps to configure the Microsoft Graph Developer Proxy. These steps are required only for initial setup:

• Open a command prompt or terminal window on your computer.
• Navigate to the directory where you have installed the Microsoft Graph Developer Proxy
• Start the proxy by running the "mgdp" command. You will get a security warning message to install certificate, click "yes" on below prompt. In order to decrypt HTTPS traffic sent from your machine, the proxy uses this certificate. This certificate will be installed in the Certificate store >> Current User >> Personal >> Certificates folder.
• Windows Defender Firewall prompt will be displayed, click "Allow access". This will allow the traffic through firewall.

The getting started documentation for the Microsoft Graph Developer Proxy can be found at the following link: https://github.com/microsoftgraph/msgraph-developer-proxy

How to use Microsoft Graph Developer Proxy

Once the prerequisites settings are completed, open a command prompt or terminal window on your computer, navigate to the directory where you have installed the Microsoft Graph Developer Proxy and start the proxy by running the "mgdp" command.

Following information is displayed when a request is intercepted using the proxy:

• Request - URL of the API intercepted
• Chaos - HTTP error code with error message.
• Warning - Guidance to build better apps like use $select for better performance in Microsoft Graph API requests etc.
• Tip - Tip to improve the API request like user Microsoft Graph SDK etc.

You can also record the request logs.

To start recording:

• Use the `–record` argument when starting the proxy, or
• press r (for record) on the keyboard

To stop recording:

• press s (for stop) on the keyboard.

Proxy can be stopped by using Ctrl+C

Configuration

All the default configuration settings are fetched from the "appsetttings.json" file located in the directory where you have installed the Microsoft Graph Developer Proxy, however you have an option to override the settings by-passing parameters in the command itself as shown below:

mgdp --no-mocks --allowed-errors 429 --failure-rate 100

There are two important files, appsettings.json and responses.json in the downloaded folder which provides control on how to use the Microsoft Graph Developer Proxy :

Appsettings. json

In this file there are several settings that you can use to control how you would like to configure the proxy. By default, Microsoft Graph and Sharepoint API's are configured in to "urlsToWatch" array of URL's. If you want to intercept requests to your custom API, add the URL of your API in this array in the same format.

rate(failureRate) and allowedErrors are other crucial configurations which are helpful to simulate errors and handle exceptions.

The following table summarizes the current available settings. For the latest configuration options, please refer the documentation here.

Setting	Description	Command-line option	Allowed values	Default value
port	The port for the proxy server to listen on	-p, --port <port>	integer	8000
logLevel	Level of messages to log	--logLevel <loglevel>	string	debug, info, warn, error
failureRate	Rate of requests to Microsoft Graph between 0 and 100 that the proxy should fail. Set to 0 to pass all requests to Microsoft Graph, and to 100 to fail all requests.	-f, --failure-rate <failurerate>	0..100	50
mocksFile	Provide a file populated with mock responses	--mocks-file <mocksfile>	text	responses.json
noMocks	Don't use mock responses	-n, --no-mocks	true, false	false
allowedErrors	List of errors that the developer proxy may produce	-a, --allowed-errors <allowederrors>	See Supported HTTP error status codes	All supported error codes
urlsToWatch	List of URLs allowed for testing	n\a	Absolute URL (can contain wildcards) eg. "https://graph.microsoft.com/v1.0/*"	See App settings file
labelMode	Set the console output label mode	n\a	string	text, icon, nerdFont

responses. json

To define the specific set of response, you can update the responses.json placed in the current directory. Appsettings.json has a parameter mocksFile to specify the name of the file.

As a mock response, you can define a URL and a URL pattern by replacing part of the URL with an * (asterisk)

e.g : 

• Specific URL: "url": https://graph.microsoft.com/v1.0/me
• Asterisk with URL: "url": https://graph.microsoft.com/v1.0/users/*

With Asterisk URL

The same mock response would be returned for:

https://graph.microsoft.com/v1.0/users/[email protected]

https://graph.microsoft.com/v1.0/users/[email protected]

Here is an example of a mock response for the API:

In this example, we will first send a request to Graph API to fetch a user profile and display on the screen. For the request to go through the proxy to Graph API we will run below command:

mgdp --failure-rate 0 --no-mocks

Then we will mock the request to display the local profile image from the folder using below command. You can explicitly mention a mock file or can configure it in appsettings.json.

mgdp --mocks-file responses.json

Below response array is used in the responses. json.

{
  "responses": [
    {
      "url": "https://graph.microsoft.com/v1.0/users/*/photo/$value",
      "method":  "GET",
      "responseBody": "@picture.jpg",
      "responseHeaders": {
        "content-type": "image/jpeg"
      }
    }
  ]
}

Summary

This article helps us to understand the basics of Microsoft Graph Developer proxy. It is an excellent tool for pro developers to simulate errors during development and build resilient applications. This tool can also be used by the code auditors and system integrators as they can test the application without modifying a single line of code.

Note: This article is written using the Microsoft Graph Developer Proxy v0.5. This tool is currently in community preview and changes are expected in the tool before it is Generally Available (GA). For the latest information related to proxy, refer to the documentation at: https://github.com/microsoftgraph/msgraph-developer-proxy