# 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

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

### REST Deprecation Example

```http
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

```graphql
# 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

```yaml
# 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)