Course contentsShow
← System Design
Lesson 1919 of 1,91945. API Design and VersioningFree lesson

API Design for Polyglot Clients and Backwards Compatibility

Designing APIs that serve web, mobile, and third-party clients while maintaining compatibility across heterogeneous ecosystems.

API Design for Polyglot Clients and Backwards Compatibility

What you'll learn: How to design APIs that gracefully serve diverse clients—web browsers, mobile apps, IoT devices, and third-party integrations—while evolving without breaking existing consumers.

The Core Challenge

When your API serves multiple client types (JavaScript SPAs, iOS/Android apps, server-side integrations, CLI tools), each has different constraints: payload size tolerance, retry logic, authentication flow support, and update cadence. A mobile app user might delay updates for months; a web client refreshes on every deploy. You must design for this heterogeneity while maintaining backward compatibility as your API evolves.

Design Principles for Polyglot Clients

Additive Changes Only: Add new fields, endpoints, or optional parameters—never remove or rename existing ones without versioning. Clients that don't recognize new fields ignore them safely.

Explicit Defaults: Return explicit values rather than relying on implicit behavior. A boolean field should send false, not be absent, so clients don't guess.

Flexible Content Negotiation: Use Accept headers to let clients request JSON, Protocol Buffers, or XML. Mobile apps might prefer compact binary formats; web prefers JSON.

Feature Detection Over Version Detection: Provide a capabilities endpoint (/api/features) so clients discover what the server supports without hardcoding version checks.

Backwards Compatibility in Practice

When evolving, treat old API versions as immutable contracts. Use techniques like gateway-level routing, where version routing directs /v1/* requests to compatible handlers while /v2/* introduces improvements. Database schema evolution must support both versions simultaneously—add nullable columns, never drop them immediately.

For breaking changes, maintain parallel versions with clear deprecation timelines, giving clients 6–12 months notice via deprecation headers and documentation.

Key Takeaway: Design APIs assuming clients evolve independently—use additive changes, explicit defaults, and content negotiation to serve heterogeneous ecosystems while maintaining strict backward compatibility through versioning and gradual deprecation.