4.16. Allowing Versioning and Evolution

4.16. Allowing Versioning and Evolution

One of the most challenging aspects of designing an application protocol is ensuring that it can evolve over time while maintaining compatibility with existing deployments.

Applications using HTTP SHOULD design for extensibility from the beginning. This includes:

• Protocol negotiation: Providing mechanisms for clients and servers to negotiate which version or features to use.

• Graceful degradation: Allowing older clients to work with newer servers (and vice versa), even if they don't support all features.

• Feature discovery: Allowing clients to discover what features a server supports.

• Ignoring unknown elements: Specifying that implementations should ignore unknown header fields, content, or other protocol elements rather than treating them as errors.

Common approaches to versioning include:

• Media type versioning: Using different media types for different versions (e.g., application/vnd.example.v1+json, application/vnd.example.v2+json).

• URL versioning: Including the version in the URL (e.g., /v1/resource, /v2/resource). However, this can create issues with caching and resource identity.

• Header field versioning: Using a custom header field to indicate the version.

• Feature-based negotiation: Rather than versioning the entire protocol, allowing negotiation of individual features.

Applications SHOULD:

• Clearly document how versioning works.

• Provide guidance on how to maintain backward compatibility.

• Consider the impact of versioning on caching and other HTTP features.

• Avoid making breaking changes to existing versions; instead, define new versions when incompatible changes are necessary.

Applications SHOULD NOT:

• Use URL query parameters for versioning, as this can interfere with caching.

• Create situations where different versions of the protocol use the same identifiers (URLs, media types) for different things.

• Force clients to upgrade immediately when new versions are released.