How would you evolve a public API without breaking existing clients?

First identify the documented contract and real client usage. Prefer additive changes, but check whether clients reject unknown fields or enum values. Introduce incompatible changes through an explicit version or migration path, publish examples, and support an agreed overlap period. Use contract tests and telemetry to detect old-client usage before removal. Deprecate with a clear timeline and rollback plan. Compatibility includes behavior, validation, error responses, and performance assumptions, not just whether the same method names and field types still exist.