إصدار واجهات API والتوافق العكسي

Once an API has clients, you cannot freely change it. Renaming a field or removing an endpoint can break every consumer. Versioning lets you evolve the API while existing clients keep working.

Know the difference:

• Non-breaking: adding a new optional field, adding a new endpoint
• Breaking: removing a field, renaming a field, changing a type, making an optional field required

Non-breaking changes can ship without a new version; breaking ones cannot.

The most visible scheme puts the version in the path. It is simple and cache-friendly, and clients can clearly see which version they call.

Alternatively, clients request a version via a header. This keeps URIs clean and treats the version as part of content negotiation.

A lighter approach uses a query parameter, e.g. ?version=2. It is easy to test in a browser but mixes versioning with regular parameters and can complicate caching.

SemVer (MAJOR.MINOR.PATCH) communicates intent:

• MAJOR: breaking changes
• MINOR: new backward-compatible features
• PATCH: backward-compatible fixes

For public HTTP APIs, the MAJOR number usually maps to the URI version.

The cheapest versioning is not needing a new version. Follow the additive rule: only add, never remove or rename. Clients ignore unknown fields, so adding is safe.

When you must retire something, deprecate first. Mark it in docs, send a Deprecation or Sunset header, and give clients a clear timeline before removal.

It is not just REST. In gRPC, never reuse or renumber protobuf field tags — that breaks the wire format. In GraphQL, the convention is no versions at all: add fields and use the @deprecated directive on old ones.

Running several versions at once has a cost. Strategies include translating old requests to the new internal model, or routing versions to different handlers. Limit how many versions you support and sunset old ones on schedule.

Reduce future pain by designing for evolution: prefer objects over bare values so you can add fields, avoid leaking internal enums, and document a clear compatibility contract from day one.

Test your understanding of API versioning.

You learned how to evolve APIs safely:

• Distinguish breaking from non-breaking changes
• URI, header, and query parameter versioning schemes
• SemVer and the additive-change discipline
• Deprecate with Sunset headers before deleting
• gRPC tag stability and GraphQL's deprecation approach