JDD2014: REST API Versioning Practice: From Header to Model (Ł. Wierzbicki)

### Overview Łukasz Wierzbicki presents a practical engineering perspective on REST API versioning, drawing directly from experiences at Kontakt.io. Facing a rapidly evolving startup environment where new API versions had to be delivered every three to four weeks while supporting thousands of external clients with production mobile apps, the company needed an architectural approach that avoided breaking contracts and minimized code duplication.

### Key Topics - **API Versioning Challenges in Fast-Paced Startups**: Balancing rapid iterations (delivering updates every 3–4 weeks) with backwards compatibility guarantees for third-party client applications published in app stores. - **Core Architecture Assumptions**: Keeping core business logic version-agnostic (avoiding sprawling `if`/`switch` statements inside business rules), versioning at the controller level, and keeping object-to-view serialization transparent. - **Architectural Approaches Considered**: 1. *Top-to-Bottom Duplication*: Duplicating controllers, services, repositories, and models across versions. Simple to understand for newcomers, but leads to massive, unsustainable code duplication. 2. *Single Model with Explicit Converters*: Maintaining a single backend model and using explicit converter classes to map models to versioned view object hierarchies. While reducing model code, it introduces high maintenance overhead for class hierarchies when fields are removed or modified. 3. *Dynamic Proxies (View Factory)*: Using runtime dynamic proxies (e.g., via `java.lang.reflect.Proxy`) with annotations and providers to map fields and inject synthetic view properties not present in the backend model. 4. *Map-Based View Factory (Chosen Solution)*: Employing a lightweight factory that transforms domain models directly into structured maps based on version configurations. The resulting map is serialized into JSON/XML transparently by serializers like Jackson. - **Pragmatic API Design vs. Pure REST**: Intentionally diverging from pure RESTful design and HATEOAS by relying strictly on `GET` (for fetching data) and `POST` (for operations/verbs in URLs like `/update` and `/delete`).

### Technical Details - **Header-Based Versioning**: Versioning metadata is passed through the HTTP `Accept` header rather than via URL paths. - **Configuration Options in Map View Factory**: - *Includes*: Specifying explicit lists of fields (including dot-notation traversal of nested objects) to copy from domain model to map. - *Excludes*: Omitting specified fields, though noted as risky when maintaining numerous versions since newly added model fields might accidentally leak into older API versions if not explicitly excluded. - *Generated Fields (Providers)*: Creating view-specific computed fields directly at response generation time without polluting domain entities. - *Field Renaming/Mapping*: Aliasing model property names to match client expectations for a specific version. - **Partial Resources**: Allowing clients to request only the specific fields they need (e.g., asking for 3 fields out of 15), reducing response payloads.

### Takeaways - Versioning strictly via header or URL is often an aesthetic or operational choice, though URL-based routing can simplify external reverse proxying and caching. - Minimizing redundant class hierarchies via dynamic map-based view generation drastically reduces maintenance burden. - Adding fields to payloads without a version bump is not always backwards compatible, as poorly configured client deserializers (such as unconfigured Jackson mappers) can fail on unexpected fields. - Maintain clean boundaries between versions in the codebase so that obsolete versions can be cleanly deprecated and deleted without complex refactoring.