MediumExperience level: 3-5 years · 8-15 years1 min read

What are the API versioning strategies, and which do you choose for a public API?

Reviewed by Gurusankar M.

Asked inAmazonMicrosoftDeloitte
#versioning#uri versioning#header versioning#media type#backward compatibility
Report issue

Short Answer

URI versioning (/v1/orders) — simplest, most visible, most common. Header/media-type versioning (Accept: ...v2+json) — cleaner URLs, harder to test. Query param (?version=2) — easy but messy. For public APIs, URI versioning wins on clarity; whichever you pick, additive changes shouldn't need a new version.

On this page

Concept Made Simple

Coffee Chat Question

“What are the API versioning strategies, and which do you choose for a public API?”

Remember It Faster

Mind Map Answer

URI /v1/
visible, cache-friendly, most common
Header/media-type
clean URLs, harder to test
Query ?v=2
easy but clutters
Best
version only on breaking changes

Think Beyond the Expected

What If?

Which changes require a new API version vs which are safe to add in place?

Additive, non-breaking changes (new optional fields, new endpoints, new optional params) should NOT bump the version — clients ignore what they don't know. Only breaking changes (removing/renaming fields, changing types/semantics, making a field required) warrant a new version.

Real World

Most public APIs (Stripe, GitHub) version deliberately and rarely; the discipline is designing additively so you almost never need v2 — versioning is the escape hatch, not the default.

Interviewer's Expectation

Keywords they're listening for:

  • URI vs header vs query
  • URI most common for public
  • additive vs breaking changes
  • minimize version bumps

Common Mistakes

  • Versioning for additive changes
  • Never deprecating old versions
  • Inconsistent versioning across endpoints

Best Practices

  • Design additively to avoid version bumps
  • Version on breaking changes only
  • Publish a deprecation policy/timeline

Follow-up Questions

  1. How does Stripe version with a date header?
  2. What counts as a breaking change?
  3. How long do you support old versions (deprecation)?

Continue Learning with AI

Take this question deeper with your favourite AI assistant. Pick a depth, copy the prompt, or open it directly — AI is your learning companion, not a shortcut.

Plain-language foundations

I'm preparing for a software engineering interview and want to understand this from scratch, as a beginner.

Topic: Versioning (REST APIs)
Interview question: "What are the API versioning strategies, and which do you choose for a public API?"

Please:
1. Explain the core idea in simple, plain language, using an everyday analogy.
2. Define any technical terms you use.
3. Walk through one small, concrete example.
4. Finish with a single sentence I can easily remember.

Keep the tone friendly and assume I'm new to this topic.
Open inChatGPTGeminiClaude

Was this answer helpful?

Affiliate links

Tools for Your Developer Workspace

Equipment for a comfortable, productive setup.

As an Amazon Associate I earn from qualifying purchases.