Question 1

What is API versioning, and how do you avoid breaking clients?

Accepted Answer

Managing change in an interface **other people depend on** — where the governing constraint is that once an API is published, you no longer control when consumers update, and in many cases they never will.

**What actually counts as a breaking change**, which is narrower than people assume:

**Breaking:** removing or renaming a field or endpoint; making an optional request parameter required; narrowing accepted input; changing a type; changing the meaning of a value; adding a new required field to a request; changing error codes or status codes clients branch on.

**Non-breaking:** adding a new optional request parameter; adding a field to a response — **provided clients tolerate unknown fields**, which must be stated in your contract; adding a new endpoint; adding a new optional value to a response enum, which is breaking if clients switch exhaustively.

**The versioning strategies:**

**URL path versioning** — `/v1/orders`. Obvious, cacheable, easy to route, and criticised because the resource identifier changes when only the representation did.

**Header or media-type versioning**, which keeps URLs stable and is harder to test casually and easier to get wrong in caching.

**Query parameter versioning**, simple and easily forgotten by clients.

**Date-based versioning**, where a client pins a date and the server applies transformations to bring old requests forward — powerful, and it requires real infrastructure.

**What matters more than the scheme:**

**Additive change wherever possible**, so most changes need no version at all.

**Expand and contract** for anything that must change: add the new field, support both, migrate consumers, then remove the old — **with measurement of who is still using it** before removal.

**Deprecation with dates and telemetry**, not just documentation. **You cannot retire what you cannot see being used.**

**A published policy** on how long versions are supported.

**Consumer-driven contract tests**, which catch breakage before release.

**Limiting the number of live versions**, since each is maintenance and divergence.

**Internal APIs can be versioned less formally**, provided you genuinely control every caller.

Question 2

What makes a good API design?

Accepted Answer

Predictability above cleverness — a good API is one where a developer can guess correctly what something is called and how it behaves, because they will guess far more often than they will read the

Question 3

What is semantic versioning and what does the caret mean?

Accepted Answer

Semantic versioning encodes intent in a three-part number. The major version increments on a breaking change, the minor on a backwards-compatible addition, and the patch on a backwards-compatible

Question 4

What is the difference between PUT and PATCH?

Accepted Answer

PUT replaces a resource entirely with the representation you send. PATCH applies a partial modification. The distinction determines what happens to fields you do not mention, and that is where most

Question 5

Why does documentation always go out of date?

Accepted Answer

Because documentation and the code it describes are coupled in meaning but decoupled in enforcement — nothing breaks when they diverge, so they diverge. The core mechanism. Code has a merciless

Question 6

What is idempotency and why does it matter for APIs?

Accepted Answer

An operation is idempotent when performing it more than once has the same effect as performing it once. Setting a value to ten is idempotent; adding ten is not. The property matters because networks

Question 7

What is the difference between rolling back and rolling forward?

Accepted Answer

Reverting to the previous version versus fixing forward with a new release — and which is appropriate depends on factors that are worth deciding before an incident rather than during one. Rollback.

Related Questions