Excursion: When to release a new API?

A version number tag indicates a certain level of backwards-compatibility that can be expected by the client, and as such, extra care should be taken to maintain this trust. The following lists show which types of changes necessitate a new version, and which don’t[1]:

[1] See <https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/>

Changes that don’t require a new version

• New resources (under a new resource path)
• New HTTP methods on existing resources (new commands)
• New data formats
• New attributes or elements on existing data types

Changes that require a new version

• Removed or renamed URIs
• Different data returned for same URI
• Removal of support for HTTP methods on existing URIs