IPA-120: Versioning

API producers should avoid incrementing the API version where possible, prioritizing supporting the current API version unless absolutely necessary. This philosophy reduces exposing our clients to the friction of migrating versions and multiple versions complicates maintenance, testing and documentation for MongoDB.

State

Adopt

Guidance

• API producers should consider whether their changes warrant a new version or can be made backward compatible
  • API producers should refer to backwards compatibility (IPA-116) prior to versioning their API
  • API producers should not version their API if the desired functionality can be achieved in a backwards compatible fashion
  • API producers should consider whether introducing a new endpoint alongside existing, in lieu of a new version
  • API producers should avoid versioning an API solely to rename existing fields or paths
• API producers may coordinate to sunset old versions faster than the default timeline of one-year
• API producers must coordinate with clients to transition to new versions to avoid impact

Further Reading

• IPA-116: Backwards compatibility