Semantic Versioning — MAJOR.MINOR.PATCH in Practice

The three numbers

• MAJOR — breaking change. Existing client code will not work without modification.
• MINOR — new backwards-compatible functionality. Existing clients are unaffected.
• PATCH — backwards-compatible bug fix.

What counts as a breaking change in an API

• Removing or renaming an endpoint.
• Removing or renaming a request/response field.
• Changing a field type (string → integer).
• Changing HTTP method for an endpoint.
• Adding a new required request field.

What is NOT a breaking change

• Adding a new optional request field (with a default).
• Adding a new response field (clients must ignore unknown fields).
• Adding a new endpoint.
• Reducing response time.

Pre-release versions

1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1 — communicate stability expectations. Pin to exact versions in production; ranges are fine in development.