How to gracefully handle resource variants in your REST API

As REST APIs develop, a common challenge is managing parameters that evolve into more complex configurations, especially when dealing with AI models that require distinct settings. The text discusses four potential approaches to structuring such APIs: maintaining a common-denominator schema, using discriminated unions, creating separate endpoints for each model, and organizing endpoints by model resources. Each option balances factors like type clarity, SDK ergonomics, and maintainability differently. The common-denominator schema offers backward compatibility but lacks client-side validation. Discriminated unions improve runtime error checking but increase type complexity. Separate endpoints simplify SDK types and enhance user experience but may lead to method proliferation. Organizing by model resources naturally groups related functionalities but can be verbose. A variant of the fourth option, adding a default model endpoint, is highlighted as user-friendly, allowing for a sensible default while accommodating model-specific configurations. The choice between these strategies depends on backend considerations and anticipated API growth, with specific options being more suitable based on whether the focus is on model configurations or functionality.