Content Encoding (Compression)

Overview

PSRESTful supports standard HTTP content encoding, allowing API clients to receive compressed responses. Compression reduces bandwidth usage and improves response times — especially for large JSON payloads like product catalogs, pricing configurations, and media content listings.

For high-volume integrations that import thousands of products across multiple suppliers, enabling compression can significantly reduce transfer sizes and speed up catalog syncs.

How It Works

PSRESTful uses standard HTTP content negotiation:

Your client sends an Accept-Encoding header listing the compression methods it supports
The API selects the best available method and compresses the response body
The response includes a Content-Encoding header indicating which method was used
Your HTTP client decompresses the response automatically

If no Accept-Encoding header is sent, the response is returned uncompressed.

Supported Compression Methods

Method	Header Value	Best For	Compatibility
Zstandard	`zstd`	Best overall performance and compression ratio	Modern clients (Chrome, Firefox, newer HTTP libraries)
Brotli	`br`	Excellent for text/JSON, smaller than gzip	Widely supported in modern clients
gzip	`gzip`	Universal fallback	All HTTP clients
deflate	`deflate`	Legacy support	All HTTP clients

Example Requests

Requesting gzip compression

curl -s -D- -o /dev/null \
  -H "X-API-Key: your-api-key" \
  -H "Accept-Encoding: gzip" \
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/"

import requests
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
    headers={
        "X-API-Key": "your-api-key",
        "Accept-Encoding": "gzip",
    },
)
 
product = response.json()

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept-Encoding": "gzip",
    },
  }
);
 
const product = await response.json();

The response headers will include:

Content-Encoding: gzip

Requesting Brotli compression

curl -s -D- -o /dev/null \
  -H "X-API-Key: your-api-key" \
  -H "Accept-Encoding: br" \
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/"

import requests
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
    headers={
        "X-API-Key": "your-api-key",
        "Accept-Encoding": "br",
    },
)
 
product = response.json()

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept-Encoding": "br",
    },
  }
);
 
const product = await response.json();

Requesting multiple methods with priority

You can list multiple methods and let the server choose the best one:

curl -s -D- -o /dev/null \
  -H "X-API-Key: your-api-key" \
  -H "Accept-Encoding: zstd, br, gzip" \
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/"

import requests
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
    headers={
        "X-API-Key": "your-api-key",
        "Accept-Encoding": "zstd, br, gzip",
    },
)
 
product = response.json()

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept-Encoding": "zstd, br, gzip",
    },
  }
);
 
const product = await response.json();

Client Library Examples

Most HTTP libraries handle gzip compression automatically. Here’s how to ensure compression is enabled or opt into newer methods.

import requests
 
headers = {
    "X-API-Key": "your-api-key",
    "Accept-Encoding": "gzip, br",
}
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
    headers=headers,
)
 
# requests automatically decompresses the response
product = response.json()

Note: The requests library sends Accept-Encoding: gzip, deflate by default. To use Brotli, install brotli or brotlicffi (pip install brotli), and requests will automatically include br in the header.

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
  {
    headers: {
      "X-API-Key": "your-api-key",
    },
  }
);
 
// Browsers and modern runtimes handle decompression automatically
const product = await response.json();

Note: Browsers automatically negotiate compression and decompress responses. In Node.js 18+, the built-in fetch also handles this automatically.

import axios from "axios";
 
const response = await axios.get(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/products/5989/",
  {
    headers: {
      "X-API-Key": "your-api-key",
    },
  }
);
 
// axios decompresses gzip/deflate/br automatically
const product = response.data;

Trade-offs

Factor	Small Responses (< 1 KB)	Large Responses (> 10 KB)
Bandwidth savings	Minimal	Significant (50–90% reduction)
Latency impact	Negligible	Noticeable improvement
CPU overhead	Not worth it	Well worth the trade-off

Compression is most impactful for:

Product catalog imports — full product data with descriptions, attributes, and part arrays
Pricing and configuration responses — complex pricing structures with many charge lines
Media content listings — media metadata across large product lines

For small responses like single inventory lookups or order status checks, the compression benefit is minimal.

Best Practices

Use gzip as your safe default. It’s universally supported and provides good compression for JSON responses.
Upgrade to Brotli or Zstandard when possible. If your HTTP client supports br or zstd, prefer them for better compression ratios and faster decompression.
List multiple methods in Accept-Encoding. Send Accept-Encoding: zstd, br, gzip and let the server select the best option. This ensures you get optimal compression without sacrificing compatibility.
Focus on large payloads. Compression has the most impact when importing catalogs or fetching product data. Don’t worry about optimizing compression for transactional endpoints with small responses.
Combine with caching. Use compression together with caching for the fastest possible catalog imports — cached responses are returned immediately, and compression reduces transfer size.

Protocol Buffers - Binary protobuf responses for smaller payloads and faster parsing
Caching - API response caching and cache bypass
Rate Limits - API usage limits

Caching Protocol Buffers