Skip to content

VERSIONING.md

Latest commit

 

History

History
291 lines (223 loc) · 9.28 KB

VERSIONING.md

File metadata and controls

291 lines (223 loc) · 9.28 KB
Raw

API Versioning Strategy

This document outlines the versioning strategy for RealEstateAPI documentation and provides guidelines for maintaining multiple API versions.

Overview

RealEstateAPI follows semantic versioning principles and maintains multiple concurrent API versions to ensure backward compatibility while enabling innovation.

Versioning Philosophy

1. Stability First

  • Existing API versions remain stable and functional
  • Breaking changes trigger new major versions
  • Security updates applied to all supported versions

2. Clear Migration Paths

  • Comprehensive migration guides between versions
  • Migration tools and utilities provided
  • Gradual deprecation with advance notice

3. Developer Experience

  • Version-specific documentation and examples
  • Clear communication about changes and timelines
  • Support during migration process

Version Lifecycle

Phase 1: Development (Pre-release)

  • Duration: Variable
  • Status: Internal development and testing
  • Access: Limited beta access
  • Documentation: Internal specifications

Phase 2: Beta (Public Beta)

  • Duration: 3-6 months
  • Status: Public beta with parallel production support
  • Access: Opt-in beta program
  • Documentation: Beta documentation with disclaimers

Phase 3: General Availability (Current)

  • Duration: 18-24 months as current version
  • Status: Recommended for new projects
  • Access: Full public access
  • Documentation: Complete documentation and examples

Phase 4: Maintenance (Legacy Support)

  • Duration: 12-18 months
  • Status: Security updates and critical fixes only
  • Access: Continued access for existing users
  • Documentation: Maintained but not enhanced

Phase 5: Deprecated (End of Life)

  • Duration: 6 months sunset period
  • Status: No updates, migration required
  • Access: Discontinued at end of sunset period
  • Documentation: Archived with migration guidance

Current Version Status

Version Phase Status Support Until Documentation
v3 GA Current Active v3 Docs
v2 Maintenance Supported Dec 2025 v2 Docs
v1 Deprecated EOL Warning Dec 2024 v1 Docs

Documentation Structure

Directory Organization

docs/
├── versions.md              # Version comparison and selection guide
├── index.md                 # Main documentation index with version selector
├── v1/                      # Version 1 documentation
│   ├── api-reference/
│   ├── authentication/
│   └── migration/
├── v2/                      # Version 2 documentation
│   ├── api-reference/
│   ├── authentication/
│   └── migration/
└── v3/                      # Version 3 documentation (current)
    ├── api-reference/
    ├── authentication/
    └── migration/

examples/
├── v1/                      # Version 1 code examples
├── v2/                      # Version 2 code examples
└── v3/                      # Version 3 code examples (current)

guides/
├── getting-started.md       # Version-agnostic getting started
├── integration-patterns.md  # Cross-version integration patterns
└── versioning.md           # This document

Content Guidelines

Version-Specific Content

  • API Reference: Complete and version-specific
  • Code Examples: Must match the API version exactly
  • Error Responses: Document version-specific error formats
  • Rate Limits: Specify version-specific limits

Shared Content

  • Authentication Basics: Common patterns across versions
  • Integration Patterns: High-level architectural guidance
  • Best Practices: General development practices

Breaking Changes Policy

What Constitutes a Breaking Change

  1. Field Removal: Removing response fields
  2. Field Renaming: Changing field names
  3. Data Type Changes: Changing field data types
  4. Required Fields: Making optional fields required
  5. Endpoint Changes: Changing URLs or HTTP methods
  6. Error Formats: Changing error response structure
  7. Authentication: Changing authentication methods

Non-Breaking Changes

  1. Field Addition: Adding new optional response fields
  2. New Endpoints: Adding new API endpoints
  3. Optional Parameters: Adding new optional request parameters
  4. Documentation: Improving documentation and examples
  5. Performance: Performance improvements
  6. Error Messages: Improving error message clarity

Migration Support

Migration Tools

  1. Assessment Tool: Analyze current API usage
  2. Field Mapper: Map fields between versions
  3. Code Generator: Generate updated code
  4. Validation Tool: Test migration completeness

Migration Process

  1. Assessment: Analyze current integration
  2. Planning: Create migration timeline
  3. Testing: Parallel testing in sandbox
  4. Gradual Rollout: Phase migration by feature
  5. Validation: Confirm migration success
  6. Cleanup: Remove old version dependencies

Support Resources

  • Migration Guides: Step-by-step instructions
  • Code Examples: Before/after code samples
  • 1:1 Support: Personal migration assistance
  • Office Hours: Regular Q&A sessions
  • Discord Channel: Community support

Context7 Integration

Version Configuration

The context7.json file includes comprehensive version information:

{
  "apiVersions": {
    "current": "v3",
    "supported": ["v1", "v2", "v3"],
    "upcoming": [],
    "deprecated": [],
    "baseUrls": {
      "v1": "https://api.realestateapi.com/v1",
      "v2": "https://api.realestateapi.com/v2",
      "v3": "https://api.realestateapi.com/v3"
    }
  },
  "versioningStrategy": {
    "documentationStructure": "version-folders",
    "backwardCompatibility": "2-versions",
    "migrationSupport": true,
    "changelogRequired": true
  }
}

Context7 Benefits

  1. Version Awareness: Context7 understands version differences
  2. Automatic Routing: Routes to appropriate version documentation
  3. Migration Assistance: Helps identify migration needs
  4. Consistency Checks: Validates version-specific examples

CI/CD Version Management

Automated Checks

  1. Version Consistency: Ensure examples match version folders
  2. Breaking Change Detection: Alert on potential breaking changes
  3. Documentation Completeness: Verify all versions have required docs
  4. Link Validation: Check version-specific links

Deployment Pipeline

  1. Validation: Run version-specific validation
  2. Testing: Test examples against correct API versions
  3. Deployment: Deploy with version-specific routing
  4. Monitoring: Monitor version-specific usage

Deprecation Process

Timeline

  • 18 months before EOL: Initial deprecation announcement
  • 12 months before EOL: Enter maintenance mode
  • 6 months before EOL: Final migration deadline
  • 3 months before EOL: Weekly reminders
  • EOL Date: Version discontinued

Communication Channels

  1. Email Notifications: Direct user notifications
  2. API Headers: Deprecation headers in responses
  3. Documentation Banners: Prominent deprecation notices
  4. Blog Posts: Public announcements
  5. Developer Newsletter: Regular updates

Support During Deprecation

  • Migration Assistance: Free migration support
  • Extended Support: Available for enterprise customers
  • Emergency Fixes: Critical security issues only
  • Documentation: Maintained until EOL + 6 months

Best Practices

For API Users

  1. Version Pinning: Always specify API version
  2. Migration Planning: Plan upgrades in advance
  3. Testing: Test in sandbox before production
  4. Monitoring: Monitor deprecation notices
  5. Community: Engage with developer community

For Documentation Maintainers

  1. Consistency: Maintain consistent structure across versions
  2. Accuracy: Keep examples up-to-date with API changes
  3. Clarity: Clearly mark version-specific content
  4. Migration: Provide clear migration paths
  5. Testing: Validate all examples regularly

Version-Specific Guidelines

v1 (Deprecated)

  • Status: End of life December 2024
  • Updates: Security fixes only
  • Migration: Required before EOL
  • Documentation: Archived but accessible

v2 (Maintenance)

  • Status: Supported until December 2025
  • Updates: Critical fixes only
  • Migration: Recommended to v3
  • Documentation: Maintained

v3 (Current)

  • Status: Active development
  • Updates: New features and improvements
  • Migration: Target for all new development
  • Documentation: Comprehensive and current

Feedback and Support

Documentation Feedback

  • GitHub Issues: Report documentation bugs
  • Pull Requests: Contribute improvements
  • Discussions: Ask questions and share ideas

Version Support

Migration Support

Questions? Contact our Developer Relations team at developers@realestateapi.com