Header Rewrites

Header rewriting allows you to modify response headers from the target server before they reach your application. This is useful for fixing compatibility issues, overriding caching behavior, or adjusting content types.

Basic Syntax

?headers[]=header-name:header-value

Common Use Cases

1. Fix Content Type Issues

// API returns wrong content type
const url = 'https://your-proxy-domain.com/?url=https://example.com/api.json&headers[]=content-type:application/json';

// Force plain text for debugging
const url = 'https://your-proxy-domain.com/?url=https://api.example.com/xml-data&headers[]=content-type:text/plain';

2. Override Caching Behavior

// Disable caching for dynamic content
const url = 'https://your-proxy-domain.com/?url=https://api.example.com/live-data&headers[]=cache-control:no-cache&headers[]=expires:0';

// Enable aggressive caching for static assets
const url = 'https://your-proxy-domain.com/?url=https://cdn.example.com/image.jpg&headers[]=cache-control:public, max-age=31536000';

3. Remove Security Headers

// Remove headers that block embedding
const url = 'https://your-proxy-domain.com/?url=https://example.com/embed-content&headers[]=x-frame-options:&headers[]=content-security-policy:';

4. Add Custom Headers

// Add CORS headers for specific origins
const url = 'https://your-proxy-domain.com/?url=https://example.com/api&headers[]=access-control-allow-origin:https://myapp.com';

// Add custom application headers
const url = 'https://your-proxy-domain.com/?url=https://example.com/api&headers[]=x-custom-app:myapp&headers[]=x-version:1.0';

5. Handle Special Characters in Header Values

// URL encode header values with special characters
const customValue = encodeURIComponent('value with spaces & symbols');
const url = `https://your-proxy-domain.com/?url=https://example.com/api&headers[]=x-custom:${customValue}`;

// Using quotes for complex values
const url = 'https://your-proxy-domain.com/?url=https://example.com/api&headers[]=link:"<https://example.com>; rel=next"';

Multiple Header Modifications

// Combine multiple header changes
const baseUrl = 'https://your-proxy-domain.com/?url=https://example.com/api';
const headers = [
  'content-type:application/json',
  'cache-control:no-cache',
  'x-frame-options:',  // Remove this header
  'x-custom-header:custom-value'
];

const fullUrl = baseUrl + '&' + headers.map(h => `headers[]=${encodeURIComponent(h)}`).join('&');

Header Formats Supported

Simple Format:

headers[]=content-type:application/json

Quoted Values:

headers[]=link:"<https://example.com>; rel=next"
headers[]=content-disposition:'attachment; filename="data.json"'

Header Removal:

headers[]=x-frame-options:
headers[]=strict-transport-security:

JavaScript Helper Function

function buildProxyUrl(targetUrl, headerRewrites = {}) {
  const encodedUrl = encodeURIComponent(targetUrl);
  let proxyUrl = `https://your-proxy-domain.com/?url=${encodedUrl}`;
  
  // Add header rewrites
  Object.entries(headerRewrites).forEach(([header, value]) => {
    const headerParam = value === null || value === '' 
      ? `${header}:` // Remove header
      : `${header}:${value}`;
    proxyUrl += `&headers[]=${encodeURIComponent(headerParam)}`;
  });
  
  return proxyUrl;
}

// Usage examples
const url1 = buildProxyUrl('https://example.com/api', {
  'content-type': 'application/json',
  'cache-control': 'no-cache',
  'x-frame-options': null // Remove this header
});

const url2 = buildProxyUrl('https://example.com/content', {
  'content-disposition': 'attachment; filename="download.json"'
});

Real-World Examples

Fix API That Returns Wrong Content Type:

// API returns text/html but contains JSON
fetch('https://your-proxy-domain.com/?url=https://broken-api.com/json-endpoint&headers[]=content-type:application/json')
  .then(response => response.json()) // Now works correctly
  .then(data => console.log(data));

Enable CORS for Specific Origin:

// Add CORS headers to non-CORS API
const corsHeaders = {
  'access-control-allow-origin': 'https://myapp.com',
  'access-control-allow-methods': 'GET, POST, PUT, DELETE',
  'access-control-allow-headers': 'Content-Type, Authorization'
};

const url = buildProxyUrl('https://no-cors-api.com/data', corsHeaders);

Download File with Custom Name:

// Force download with specific filename
const url = 'https://your-proxy-domain.com/?url=https://example.com/report.pdf&headers[]=content-disposition:attachment; filename="monthly-report.pdf"';

fetch(url)
  .then(response => response.blob())
  .then(blob => {
    const downloadUrl = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = downloadUrl;
    a.download = 'monthly-report.pdf';
    a.click();
  });

Limitations & Security

• ✅ Can modify: Content-Type, Cache-Control, CORS headers, custom headers
• ❌ Cannot modify: Set-Cookie, Host, Authorization (these are filtered for security)
• ⚠️ Security: Header rewriting affects browser behavior - use carefully
• ⚠️ Encoding: Always URL-encode header values with special characters
• ⚠️ Order: Headers are processed in the order they appear in the URL

Debugging Header Rewrites

Use browser DevTools to verify headers are being applied correctly:

// Add a debug header to track modifications
const url = 'https://your-proxy-domain.com/?url=https://example.com/api&headers[]=x-debug:rewrite-applied&headers[]=content-type:application/json';

fetch(url)
  .then(response => {
    console.log('Headers:', [...response.headers.entries()]);
    console.log('Debug header:', response.headers.get('x-debug'));
    return response.json();
  });