Adding a Random String to our JSON APIs: Building for Extensibility from Day One

When designing APIs, one of the biggest challenges developers face is ensuring that future changes won't break existing client implementations. Too often, we've seen well-intentioned clients that parse JSON responses in rigid ways, hardcoding field positions or making assumptions about response structure that later prevent API evolution.

That's why we've decided to add random fields to our JSON API responses – a proactive approach inspired by successful implementations from Chrome and Let's Encrypt.

The Problem: Rigid Client Implementations

JSON APIs are designed to be extensible. The JSON specification inherently supports the addition of new fields without breaking existing parsers. However, the reality is more complex. Many client developers, whether due to time constraints, inexperience, or misunderstanding, create implementations that are intolerant of change.

Common problematic patterns include:

• Hardcoding array indices instead of using field names
• Rejecting responses that contain unknown fields
• Making assumptions about field ordering
• Implementing overly strict validation that fails on new properties

These implementation choices create a significant burden for API maintainers. Every new field or enhancement becomes a potential breaking change, stifling innovation and preventing the natural evolution of the API.

Learning from the Experts

Our approach draws inspiration from two notable examples in the tech industry:

Chrome's TLS Extension Randomization

Chrome implemented TLS ClientHello extension permutation to prevent servers from expecting a certain fixed order of extensions, which could limit Chrome from making future modifications to its TLS implementation. By randomizing the order of TLS extensions, Chrome ensured that server implementations couldn't rely on specific ordering, making the entire TLS ecosystem more robust to future changes.

Let's Encrypt's Directory Randomization

Let's Encrypt added keys with randomly generated names to their directory endpoint to dissuade client developers from writing clients in such a way that prevents them from adding new keys in the future. This proactive measure addressed the challenge they faced with early ACME clients that were intolerant of new fields, which made it difficult to introduce new functionality.

Both approaches share a common philosophy: introduce variability early to prevent ossification of client behavior.

Our Implementation Strategy

Following these examples, we're implementing random field injection in our JSON API responses. Here's how it works:

Random Field Generation

{
  "success": true,
  "result": {
    "email": "user@gentlent.com",
    "i5dgf3": "https://gentl.net/random-api",
    "id": "1647603024929000000",
    "profile_img": "https://www.gravatar.com/avatar/4584d61ab0bef9513f93a273ac985488?r=pg&d=identicon&s=128",
    "reseller_id": "12",
    "support_plan": "basic",
    "username": "user"
  }
}

Key Characteristics

• Random field names: Each response includes 1-2 fields with randomly generated names
• Predictable values: The field values point to documentation explaining the purpose
• Nested inclusion: Random fields appear both at the root level and within nested objects
• Documentation links: Field values reference our API extensibility guidelines

Implementation Guidelines

• Field names follow the pattern:
  randomField_[5-character-string]
  or
  randomProperty_[5-character-string]
• Values always link to our documentation to help developers understand the purpose
• Random fields are generated server-side for each response
• Fields are injected at various levels of nesting to test comprehensive parsing

Benefits for Long-term API Health

This approach provides several key advantages:

Immediate Feedback: Clients that break on unknown fields will fail immediately during development, not months later when we introduce new features.

Developer Education: The documentation links in random field values help educate client developers about proper JSON parsing practices.

Ecosystem Resilience: By normalizing the presence of unknown fields, we create a more robust ecosystem that can adapt to future changes.

Reduced Breaking Changes: Future API enhancements become additive rather than breaking, reducing versioning complexity.

Implementation Scope

Currently, this randomization only affects our JSON object responses. Other API formats and endpoints remain unchanged while we evaluate the effectiveness of this approach. We're monitoring client feedback and will expand the implementation based on results.

Best Practices for Client Developers

If you're building clients that consume our APIs, here are the recommended approaches:

✅ Do:

• Parse JSON responses using field names, not positions
• Ignore unknown fields gracefully
• Use proper JSON parsing libraries that handle extensibility
• Implement flexible response handling

❌ Don't:

• Hardcode field positions or array indices
• Reject responses containing unknown properties
• Make assumptions about field ordering
• Implement strict validation that breaks on new fields

Looking Forward

This change represents our commitment to building APIs that can evolve gracefully over time. By introducing controlled variability now, we're ensuring that future enhancements won't become breaking changes for well-implemented clients.

The random fields serve as a gentle but persistent reminder that JSON APIs are designed to be extensible. Clients that handle these fields correctly will seamlessly adapt to future API improvements, while those that don't will receive immediate feedback during development.

We believe this proactive approach, inspired by successful implementations in the broader tech ecosystem, will result in a more robust and future-proof API platform for all our users.

Share article

Recent Articles

Introducing Audit Logs

August 20, 2025

A letter from the founders.

June 12, 2025

Gentlent UG is now Gentlent GmbH

June 12, 2025