Charles Proxy : Developer’s Guide

Objective

If I have to recommend must-have-developer-tool that every developer should have (or, learn) then Charles will be one of them. And, for a mobile developer it’s a must tool which you can have in your toolkit bag. I realised it’s true power very late in my development career, earlier I used it as HTTP Network Monitoring Tool, but it’s definitely more than this.
Yes, I am totally in for purchasing this product. And, we need to takeout some time and thanks Karl von Randow for this — For Creating this Primer✌️

Agenda

1. Setup Charles
2. Monitor HTTP Traffic
3. Mock Response
4. Breakpoint
5. Rewrite
6. Throttling
7. Repeat
8. Troubleshooting Charles

Setup

1. Install Charles from Official Website and Start Recoding — Top Red Button.
2. Next, you need to do is to install Certificates on your mac and physical device (iOS or android).

🐞 Note: Here, I will be considering my phone as iPhone, but android has almost same steps.

Install Certificate on Mac —

Go to Charles > Help > SSL Proxy > Install Certificate

And, by clicking over — Save Charles Root Certificate. You get a *.cer file, which you need to double click to put it in Keychain.

Now, its time to install certificate on your iPhone—

1. Go to Charles > Help > Local IP and remember this IP 😅
2. Take out your iPhone, Open Settings, connect to the same Wifi Network where your Mac is on — Settings > Wifi > Tap on the (i) of Connected Wifi > Configure Proxy > Select Manual
3. Server : Same IP which you got in step-1
   Port: 8888
   Authentication: false

1. After that, you will get an alert on your Mac, to allow the device is being proxied. Please select allow else, your device won’t be monitored.
   After being connect to the same network.
2. Go to safari and open — https://chls.pro/ssl (make sure, you install certificate when you iPhone is proxied with Charles ⚠️).
3. You will get a pop-up something like — This website is trying to download a configuration profile. Do you want to allow this? Allow for the time being. And, then you will get Profile Downloaded ✅

4. Go to Settings > General > VPN & Device Management > There you will see a Downloaded Profile — Charles Proxy Custom Root Certificate , tap over it and Install the certificate.

5. Now, you will see it’s successfully installed and lied under — Configuration Profiles.

6. One more step is left, Go back to Settings > General > About > Certificate Trust Settings > Turn On the Charles Root Custom Certificate (by default, it’s turned off)

7. Finally, you are Done with Charles Setup 🚀

Monitor HTTP Traffic

If your Charles has been established, then you can see the network traffic of your device. Here, I was trying to open https://jsonplaceholder.typicode.com/users in the safari, and then you will see traffic in tree form.

Meanwhile, Right click on https://jsonplaceholder.typicode.com from Charle’s Tree and select Enable SSL Proxying for this hostname.
Note: If you won’t do this step, then your can’t read your traffic data, as it will be in encrypted form — HTTPS SSH/TLS is the culprit ⚠️

As you can see, Overview tab has the metadata like, Hostname, DNS Address, HTTP Response Code, HTTP Method, Protocol name, all the timestamp which you will need in metric calculation — response time, latency, handshake timestamp.

Next one is Request tab, which will show the request HTTP data. Since, this is a GET request, so won’t see any body here except the headers and HTTP params.

And, in Response tab, you will find the HTTP response. It will have the headers, HTTP body and Raw HTTP data (if, you are interested in it). For me, JSON text is all I need, coz this is where the HTTP Body is preety printed.

Mock Response

I mock response, you will learn two ways to mock your response — Local and Remote.

Say, you are a mobile developer and you are working on your app where you are getting the JSON data of a user from a GET API — (https://jsonplaceholder.typicode.com/users/1), but you want to reproduce a weird case with some ill value.

Positive Expected Response:

{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
}

Now, you want a response where name is null, address is empty (just to ensure app won’t malfunction if such response come to client).
So, I made a JSON like this —

{
"id": 1,
"name": null,
"username": "Bret",
"email": "Sincere@april.biz",
"address": {},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
}

Charles enable you to mock the response of https://jsonplaceholder.typicode.com/users/1 by Map Locale.

Charles > Tools > Map Local, enable the Map Local and Add.

And, while mocking you need to select the *.json file path which will be your source of truth. I have create one by the mock_response.json . This JSON will override the server’s JSON response.

Now, when I request for https://jsonplaceholder.typicode.com/users/1 then I will get the Mocked JSON response instead of actual response which server is serving. Let me show it you —

📕 Notebook: When you want to reproduce a very peculiar API response, then you can use this Map Local and serve it to client.

And, there is other alternative for this — Map Remote, as name suggest it will route a API path to different API path.
Say, you want to redirect /posts/1 to /users/1 API. Whenever user is trying to request for https://jsonplaceholder.typicode.com/posts/1, it will further redirected to https://jsonplaceholder.typicode.com/users/1 . I hardly used this in my day-to-day life, but now you know what to do if anything similar comes to you.

Charles > Tools > Map Remote > Enable > Add

Breakpoint

Breakpoint is something which will help you in altering the HTTP request or response. By altering i mean — Alter Headers, Body anything you want.

To enable breakpoint, you have to —

Charles > Proxy > Breakpoint Settings > Enable Breakpoint > Add

Here, I have added breakpoint for jsonplaceholder.typicode.com for every request and response. This is behave like an interceptor.
Each time, you create a HTTP Request, Charles will pop up a breakpoint for the request where you can alter the HTTP request.

Here, I won’t change in the request as of now, so I will select Execute. Soon, you will get another Breakpoint window which will show Edit Response —

Here, I will change the username in JSON to abhishekRavi and tap on Execute.

Yes, now you can see the magic. Client will be server with a username where value is abhishekRavi.

📕 Notebook: You can use breakpoint to modify HTTP request/ response, be it headers, status code, JSON body or anything. You are free to do anything.

Rewrite

It is more of a improved version of Breakpoint. Rewrite is more of a pre-defined breakpoint. You can set rule of certain API endpoint.

Charles > Tools > Rewrite > Enable > Add > Create Location and Action

Here, I have create a JSOnPlaceholder rule and mentioned the Remote Location or API Path, whatever you want to say and then in Body I have asked to rename ‘title’ to ‘t00tle’.

Same, you can do it with Headers and Body. I can set regex (If you are god’s favourite child and you know how to write regex then it’s for you 😄) .
Here, I tried to set a rule where HTTP Status code turn from 200 to 400.

📕 Notebook: If you want to repeat some task, then you can write rule for such task.

Throttling

This is something which is very usefull for App Developer, say you want some API to have high latency and want to test how your app behaves. You can configure the Charles Throttler, just to play with the response time and bandwith.
First, set the Throttler Settings and then start the Throttler. I always go with the 56Kbps Modem preset.

Charles > Proxy > Start Throttler

Repeat

Say, you know a API which is failing intermittently and you want to test the load of the API, the Charles have a feature called Repeat which will allow you to call API n-number of times in concurrent fashion.

By Right clicking on the API endpoint, and select Repeat Advance —

And, you can configure your repeat settings —

Say Iteration will be 100 and Concurrency will be 3 which is equivalent to — You will hit 100 HTTP API Requests in a batch of 3 request each time.

📕 Notebook: Mostly I use this to load test the API, if it’s responding with 2xx or not.

Troubleshoot

1. Can’t Install the SSL Certificate when I visit Charles Website

First, you need to check if your iPhone and Mac are on same Wifi Network and your have configured Manual Proxy on your iPhone. Refer Setup section of this article.
Second, still you are not getting the pop-up to download the Profiles then you need to change your IP Address from Mac Settings > Network Preference > Advance > TCP/IP > Renew DHCP Lease .

2. Response is always in Encrypted for me.

First, check if you have Enabled SSL Proxying for the Hostname. You can verify by right clicking over the host name from tree and check if it’s Enable SSL Proxying (i.e. you haven’t enabled it yet) or Disabled SSL Proxy (i.e. it’s already been enabled). Or, you can verify from Overview —

Second, you can delete and reinstall your certificate from Phone Setting > General > VPN & Device Management > Select Charles Profile > Remove Profile. Yes, just do a fresh start.

Conclusion

Charles is a proxy application which will sit between the client and server & help you to monitor the HTTP traffic. You can manipulate the request and response as per your need. There are way more features than we have discussed above. You can try Proxyman as an alternative of Charles.