gru_emoney_token-factory/docs/api/versioning-policy.md

API Versioning Policy

This document defines the versioning strategy for all API types in the eMoney Token Factory system.

Versioning Schemes

REST API

• URL-based versioning: /v1/, /v2/, etc.
• Additive changes only: New fields, endpoints, or query parameters are allowed
• Breaking changes: Require new version (e.g., /v2/)
• Deprecation window: Minimum 6 months before removal

GraphQL API

• Schema versioning: Single schema with deprecation warnings
• Field deprecation: Use @deprecated directive
• Breaking changes: Add new fields, deprecate old ones
• Removal: After deprecation period (minimum 6 months)

AsyncAPI

• Event type versioning: triggers.state.updated.v1, triggers.state.updated.v2
• Event envelope: Versioned separately
• Backward compatibility: Old event types supported for 6 months

gRPC/Protobuf

• Package versioning: emoney.orchestrator.v1, emoney.orchestrator.v2
• Service versioning: New service versions for breaking changes
• Message compatibility: Follow Protobuf compatibility rules

Breaking Change Definition

A change is considered breaking if it:

1. Removes an endpoint, field, or parameter
2. Changes the type of a field or parameter
3. Changes the semantics of an endpoint
4. Removes an enum value
5. Changes authentication requirements
6. Changes error response format

Non-Breaking Changes

These changes are allowed without version bump:

1. Adding new endpoints
2. Adding optional fields to requests/responses
3. Adding new enum values
4. Adding new query parameters
5. Improving error messages
6. Adding new response fields

Deprecation Process

1. Announcement: Mark as deprecated in API documentation
2. Warning Period: 6 months minimum
3. Removal: Remove in next major version

GraphQL Deprecation Example

type Token {
  code: String!
  address: String!
  oldField: String @deprecated(reason: "Use newField instead")
  newField: String!
}

REST Deprecation Example

GET /v1/tokens
Deprecation: true
Sunset: 2024-07-01
Link: <https://api.emoney.example.com/docs/v2>; rel="successor-version"

Version Lifecycle

1. Alpha: Internal testing only
2. Beta: Public beta, may have breaking changes
3. Stable: Production-ready, follows versioning policy
4. Deprecated: Scheduled for removal
5. Sunset: No longer supported

Migration Guide

When a new version is released:

1. Provide migration guide in documentation
2. Offer SDK updates
3. Provide compatibility layer if possible
4. Support both versions during transition period

Examples

REST API Versioning

/v1/tokens          # Version 1
/v2/tokens          # Version 2 (breaking changes)
/v1/tokens          # Still supported during transition

GraphQL Deprecation

# v1
type Token {
  oldName: String!
}

# v2 (additive)
type Token {
  oldName: String! @deprecated(reason: "Use name instead")
  name: String!
}

# v3 (removal)
type Token {
  name: String!
}

AsyncAPI Versioning

# v1
channels:
  triggers.created.v1:
    # ...

# v2
channels:
  triggers.created.v2:
    # ...
  triggers.created.v1:  # Still supported
    # ...

Compliance

All API changes must:

1. Follow semantic versioning principles
2. Maintain backward compatibility within major version
3. Provide deprecation warnings before removal
4. Document migration path
5. Support transition period (minimum 6 months)