How should API versioning be handled for the address service?

How should API versioning be handled for the address service?

• A. Version only via file names
• B. Version only in database schema
• C. Never version APIs
• D. Use versioned endpoints (e.g., /v1/addresses) or header-based versioning; communicate deprecations clearly and maintain backward compatibility with migration guides

Answer: (D)

Versioning APIs is about controlling how the surface you expose to clients changes over time. The best approach is to provide explicit versions of the API and route clients to a specific version, either through versioned endpoints (for example, /v1/addresses) or through headers that indicate the requested version. This creates a clear contract that clients can rely on, while allowing older integrations to continue functioning as you introduce improvements. Why this works well: when you add a change—such as a new field, different validation rules, or a redesigned response structure—you can publish a new version without breaking existing clients. The old version stays in place for as long as you need it, giving teams time to migrate. Communicating deprecations with concrete timelines and offering migration guides helps developers update their code, tests, and deployment pipelines without guesswork, reducing risk and downtime. In the address service, changes to address formats, normalization behavior, or added metadata are common reasons to version. Versioned endpoints let you evolve the API surface while keeping previous behavior intact for current users, and migration guides provide the concrete steps teams should follow to move to the newer version. Versioning only via file names or only in the database schema doesn’t provide a reliable, discoverable contract for API clients. File-name versions don’t enforce a stable API surface, and database-schema changes behind the scenes can alter behavior without signaling to clients what to expect. Never versioning APIs leads to breaking changes with each update, hurting stability and vendor trust.

Versioning APIs is about controlling how the surface you expose to clients changes over time. The best approach is to provide explicit versions of the API and route clients to a specific version, either through versioned endpoints (for example, /v1/addresses) or through headers that indicate the requested version. This creates a clear contract that clients can rely on, while allowing older integrations to continue functioning as you introduce improvements.

Why this works well: when you add a change—such as a new field, different validation rules, or a redesigned response structure—you can publish a new version without breaking existing clients. The old version stays in place for as long as you need it, giving teams time to migrate. Communicating deprecations with concrete timelines and offering migration guides helps developers update their code, tests, and deployment pipelines without guesswork, reducing risk and downtime.

In the address service, changes to address formats, normalization behavior, or added metadata are common reasons to version. Versioned endpoints let you evolve the API surface while keeping previous behavior intact for current users, and migration guides provide the concrete steps teams should follow to move to the newer version.

Versioning only via file names or only in the database schema doesn’t provide a reliable, discoverable contract for API clients. File-name versions don’t enforce a stable API surface, and database-schema changes behind the scenes can alter behavior without signaling to clients what to expect. Never versioning APIs leads to breaking changes with each update, hurting stability and vendor trust.