Repair API Version Negotiation Bugs

The problem

API versioning often breaks when header parsing, routing logic, and state management disagree across service boundaries. These inconsistencies lead to leaking internal errors, cache poisoning via incorrect Vary headers, or broken backward compatibility for legacy clients.

What it does

• Identifies mismatches between path, header, and media-type versioning sources.
• Aligns version negotiation across identity, validation, and state ownership layers.
• Corrects cache policy and Vary key headers to prevent version collisions.
• Implements version-aware request routing and schema dispatch logic.
• Generates deterministic local fixtures and regression tests for version boundaries.

Frameworks & tools

Works with any backend stack using Read, Edit, and Bash tools. Applicable to REST, GraphQL, and gRPC gateways, as well as proxy configurations like Nginx or Envoy.

Why this beats prompting it yourself

Manual prompts often miss the edge cases of versioned state ownership and cleanup. This skill enforces a canonical contract for identity and validation before irreversible mutations occur, ensuring deprecation policies are actually respected in code, not just docs.

Use cases

• Fixing inconsistent version detection between a proxy and an application server.
• Correcting state leakage where a v2 request mutates state owned by a v1 handler.
• Resolving cache poisoning caused by missing version metadata in cache keys.
• Standardizing 406 Not Acceptable or 415 Unsupported Media Type responses.