Skip to main content

Versioning

Breaking Changes Policy​

Semantic Versioning​

The PWR API follows semantic versioning with explicit version control via URL paths:

  • Major version (v1, v2): In the URL path (e.g., /v1/sites, /v2/sites)
  • Minor/patch updates: Behind the current major version (non-breaking changes only)

What Constitutes a Breaking Change​

Breaking changes require a new major version and include:

  • ❌ Removing an endpoint
  • ❌ Removing a required request parameter or field
  • ❌ Changing a response field type
  • ❌ Renaming a response field
  • ❌ Removing a response field
  • ❌ Changing an endpoint's HTTP method
  • ❌ Narrowing validation rules (making parameters more restrictive)
  • ❌ Removing or reordering existing enum values

What Is NOT a Breaking Change​

Non-breaking changes can occur at any time without a major version bump:

  • ✅ Adding new optional request parameters
  • ✅ Adding new response fields
  • ✅ Adding new enum values to existing enums
  • ✅ Extending error codes (new HTTP status codes)
  • ✅ Adding new endpoints
  • ✅ Adding new services