651ff4f7eb
- Add Foundry project configuration (foundry.toml, foundry.lock) - Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.) - Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI) - Add comprehensive test suite (unit, integration, fuzz, invariants) - Add API services (REST, GraphQL, orchestrator, packet service) - Add documentation (ISO20022 mapping, runbooks, adapter guides) - Add development tools (RBC tool, Swagger UI, mock server) - Update OpenZeppelin submodules to v5.0.0
154 lines
3.4 KiB
Markdown
154 lines
3.4 KiB
Markdown
# 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)
|
|
|