Protocol Buffers

Overview

PSRESTful supports binary Protocol Buffer (protobuf) responses as an alternative to JSON on a subset of read-only endpoints. Protobuf encodes data into a compact binary format that is smaller on the wire and faster to parse than JSON — making it a good fit for high-volume integrations that process large catalogs or poll inventory frequently.

For typical usage (browsing docs, calling a few endpoints, debugging) JSON is the better choice. Protobuf is worth considering when you are:

• Importing large product catalogs across many suppliers where every kilobyte and millisecond adds up
• Polling inventory at high frequency and want to minimize bandwidth and parse time
• Building server-to-server pipelines where human readability is not a concern

How It Works

PSRESTful uses standard HTTP content negotiation:

1. Your client sends an Accept: application/protobuf header with the request
2. The API serializes the response into the binary protobuf format
3. The response is returned with a Content-Type: application/protobuf header
4. Your client deserializes the binary payload using the matching proto definition

If no Accept header is sent (or the value is application/json), the response is returned as JSON as usual.

Supported Endpoints

JSON vs Protobuf Comparison

Example Requests

curl -s \
  -H "X-API-Key: your-api-key" \
  -H "Accept: application/protobuf" \
  -o response.bin \
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/?productId=5989"

import requests
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/",
    params={"productId": "5989"},
    headers={
        "X-API-Key": "your-api-key",
        "Accept": "application/protobuf",
    },
)
 
# response.content contains the raw binary protobuf payload
raw_bytes = response.content

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/?productId=5989",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept": "application/protobuf",
    },
  }
);
 
// response body is binary — read it as an ArrayBuffer
const buffer = await response.arrayBuffer();

The response headers will include:

Content-Type: application/protobuf

Deserializing Responses

Python — using psdomain

The psdomain package ships the compiled proto definitions for every supported service. Install it and use the generated message classes to parse the binary response.

pip install psdomain

import requests
from psdomain.proto.inventory.v2 import GetInventoryLevelsResponse
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/",
    params={"productId": "5989"},
    headers={
        "X-API-Key": "your-api-key",
        "Accept": "application/protobuf",
    },
)
 
inventory = GetInventoryLevelsResponse()
inventory.ParseFromString(response.content)
 
for part in inventory.inventory.part_inventory_array:
    print(f"{part.part_id}: {part.quantity_available.quantity.value}")

JavaScript — using protobufjs

You can load the .proto definition files and decode the binary response with protobufjs.

import protobuf from "protobufjs";
 
// Load the proto definition (download from psdomain or vendor into your project)
const root = await protobuf.load("inventory_v2.proto");
const ResponseType = root.lookupType(
  "inventory.v2.GetInventoryLevelsResponse"
);
 
const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/?productId=5989",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept": "application/protobuf",
    },
  }
);
 
const buffer = await response.arrayBuffer();
const inventory = ResponseType.decode(new Uint8Array(buffer));
 
for (const part of inventory.inventory.partInventoryArray) {
  console.log(`${part.partId}: ${part.quantityAvailable.quantity.value}`);
}

Combining with Compression

Protobuf responses can be compressed just like JSON responses. Send both headers together for the smallest possible payload:

curl -s \
  -H "X-API-Key: your-api-key" \
  -H "Accept: application/protobuf" \
  -H "Accept-Encoding: zstd, br, gzip" \
  -o response.bin \
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/?productId=5989"

import requests
from psdomain.proto.inventory.v2 import GetInventoryLevelsResponse
 
response = requests.get(
    "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/",
    params={"productId": "5989"},
    headers={
        "X-API-Key": "your-api-key",
        "Accept": "application/protobuf",
        "Accept-Encoding": "zstd, br, gzip",
    },
)
 
# requests decompresses automatically; content is the raw protobuf bytes
inventory = GetInventoryLevelsResponse()
inventory.ParseFromString(response.content)

const response = await fetch(
  "https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/?productId=5989",
  {
    headers: {
      "X-API-Key": "your-api-key",
      "Accept": "application/protobuf",
      "Accept-Encoding": "zstd, br, gzip",
    },
  }
);
 
// Browser decompresses automatically; read the protobuf bytes
const buffer = await response.arrayBuffer();

See Compression for more details on supported encoding methods.

Trade-offs

Best Practices

1. Start with JSON, upgrade selectively. Use JSON for development, testing, and low-volume calls. Switch to protobuf only for the specific endpoints where payload size or parse time is a bottleneck.

2. Combine with compression. Protobuf + gzip (or Brotli/Zstandard) gives you the smallest possible transfer size. See Compression.

3. Pin proto definitions to the API version. The proto message schemas correspond to specific PSRESTful API versions. When you upgrade to a new API version, update your psdomain package to match.

4. Check the Content-Type header for fallback. If the server cannot produce a protobuf response (unsupported endpoint, server error), it will return JSON instead. Always check Content-Type before deserializing:

if response.headers["Content-Type"] == "application/protobuf":
    inventory = GetInventoryLevelsResponse()
    inventory.ParseFromString(response.content)
else:
    inventory = response.json()

Related Documentation

• Compression — HTTP compression with gzip, Brotli, and Zstandard
• Caching — API response caching and cache bypass
• Rate Limits — API usage limits