Understanding HAR Files: A Developer's Guide

As a developer, you have likely encountered situations where you need to debug network requests, analyze API performance, or share request details with teammates. This is where HAR files become your best friend. In this comprehensive guide, we will explore everything you need to know about HTTP Archive files.

What is a HAR File?

HAR stands for HTTP Archive, a JSON-formatted file that logs all network requests made by a web browser or application. Think of it as a complete recording of every HTTP conversation between your browser and the servers it communicates with.

The HAR format was created by the Web Performance Working Group and is now supported by all major browsers and many development tools. It provides a standardized way to export, share, and analyze network traffic.

HAR File Structure

A HAR file is structured as a JSON object with a specific schema. Here is the high-level structure:

{
  "log": {
    "version": "1.2",
    "creator": {
      "name": "Browser Name",
      "version": "1.0"
    },
    "entries": [
      // Array of request/response pairs
    ],
    "pages": [
      // Optional page information
    ]
  }
}

The Entries Array

The most important part of a HAR file is the entries array. Each entry represents a single HTTP request/response cycle and contains:

{
  "startedDateTime": "2024-12-26T10:00:00.000Z",
  "time": 150,
  "request": {
    "method": "GET",
    "url": "https://api.example.com/users",
    "headers": [...],
    "queryString": [...],
    "postData": {...}
  },
  "response": {
    "status": 200,
    "statusText": "OK",
    "headers": [...],
    "content": {
      "size": 1024,
      "mimeType": "application/json",
      "text": "{...}"
    }
  },
  "timings": {
    "blocked": 0,
    "dns": 5,
    "connect": 25,
    "send": 1,
    "wait": 100,
    "receive": 19
  }
}

How to Create HAR Files

You can create HAR files from any major browser. Here is how to do it in each:

Google Chrome

1. Open DevTools

   Press F12 or right-click anywhere and select "Inspect"

2. Go to the Network tab

   This is where all network activity is recorded

3. Clear existing entries

   Click the clear button (circle with a line) to start fresh

4. Perform your actions

   Navigate the site and trigger the API calls you want to capture

5. Export the HAR file

   Right-click in the request list and select "Save all as HAR with content"

Firefox

1. Open Developer Tools (F12)
2. Select the Network tab
3. Perform your actions on the page
4. Right-click and choose "Save All As HAR"

Safari

1. Enable Developer menu in Preferences > Advanced
2. Open Web Inspector from the Develop menu
3. Go to the Network tab
4. Click "Export" to save as HAR

What Data Does a HAR File Contain?

A HAR file captures comprehensive information about each request:

Request Information

• URL: The complete URL including query parameters
• Method: GET, POST, PUT, DELETE, PATCH, etc.
• Headers: All request headers including cookies and authentication
• Body: Request payload for POST/PUT/PATCH requests
• Cookies: All cookies sent with the request

Response Information

• Status Code: HTTP status (200, 404, 500, etc.)
• Headers: All response headers including cache controls
• Body: The complete response content (JSON, HTML, etc.)
• Size: Content size before and after compression

Timing Information

• DNS Lookup: Time to resolve domain name
• Connection: Time to establish TCP connection
• SSL/TLS: Time for HTTPS handshake
• Time to First Byte: Server processing time
• Content Download: Time to receive the response

Common Use Cases for HAR Files

1. Debugging API Issues

When an API call fails or returns unexpected data, a HAR file captures the exact request that was sent. This is invaluable for debugging because you can see:

• The exact headers and payload that were sent
• The complete error response from the server
• Whether the request was cached or fresh

2. Performance Analysis

HAR files include detailed timing data that helps identify performance bottlenecks:

• Slow DNS lookups indicating infrastructure issues
• Long wait times suggesting server-side problems
• Large download times pointing to oversized responses

3. Bug Reports

When reporting bugs to developers or support teams, attaching a HAR file provides complete context. Instead of describing "the API returns an error," you can share the exact request and response.

4. API Documentation

By capturing real API traffic, you can generate documentation from actual usage patterns. This is especially useful for undocumented or third-party APIs. Tools like ProxyKit can convert HAR files directly to OpenAPI specifications.

5. Security Auditing

Security professionals use HAR files to analyze what data applications send over the network. This helps identify:

• Sensitive data being transmitted insecurely
• Unnecessary data exposure
• Third-party tracking and analytics calls

Viewing and Analyzing HAR Files

While HAR files are plain JSON, they can be quite large and difficult to read manually. Several tools can help you analyze them:

Browser DevTools

Most browsers allow you to import HAR files back into the Network tab for visual analysis. In Chrome, simply drag and drop a HAR file onto the Network panel.

ProxyKit HAR Viewer

Our free HAR file viewer provides a clean interface for:

• Filtering requests by method, status, or content type
• Searching through request and response data
• Exporting to OpenAPI or Postman formats
• Viewing formatted JSON responses

Command Line Tools

For automation and scripting, you can use tools like jq to parse HAR files:

# List all URLs from a HAR file
cat file.har | jq '.log.entries[].request.url'

# Find all POST requests
cat file.har | jq '.log.entries[] | select(.request.method == "POST")'

Best Practices When Working with HAR Files

1. Clear the network log first: Start with a clean slate to avoid capturing irrelevant requests
2. Preserve the log: Disable "Clear on navigate" if you need to capture requests across page loads
3. Include content: Always save "with content" to capture response bodies
4. Sanitize sensitive data: Remove or redact tokens, passwords, and personal information before sharing
5. Add context: When sharing HAR files for debugging, include notes about what you were trying to do

HAR File Limitations

While HAR files are powerful, they have some limitations:

• Client-side only: HAR files only capture what the browser sees, not server-side details
• No WebSocket content: WebSocket message content is typically not captured
• Binary content: Large binary files may be truncated or excluded
• CORS issues: Some cross-origin responses may have limited content

Conclusion

HAR files are an essential tool in every web developer's toolkit. They provide a standardized, portable way to capture, share, and analyze HTTP traffic. Whether you are debugging a tricky API issue, optimizing performance, or documenting endpoints, understanding HAR files will make you more effective.

Next time you need to debug a network issue or understand an API, remember that a HAR file is just a right-click away in your browser's DevTools.