# Findings Ledger API Deprecation Policy
# DEVOPS-LEDGER-OAS-63-001-REL

version: "1.0.0"
created: "2025-12-14"

policy:
  # Minimum deprecation notice period
  notice_period_days: 90

  # Supported API versions
  supported_versions:
    - version: "v1"
      status: "current"
      sunset_date: null
    # Future versions will be added here

  # Deprecation workflow
  workflow:
    - stage: "announce"
      description: "Add deprecation notice to API responses and docs"
      actions:
        - "Add Sunset header to deprecated endpoints"
        - "Update OpenAPI spec with deprecation annotations"
        - "Notify consumers via changelog"

    - stage: "warn"
      description: "Emit warnings in logs and metrics"
      duration_days: 30
      actions:
        - "Log deprecation warnings"
        - "Increment deprecation_usage_total metric"
        - "Send email to registered consumers"

    - stage: "sunset"
      description: "Remove deprecated endpoints"
      actions:
        - "Return 410 Gone for removed endpoints"
        - "Update SDK to remove deprecated methods"
        - "Archive endpoint documentation"

  # HTTP headers for deprecation
  headers:
    sunset: "Sunset"
    deprecation: "Deprecation"
    link: "Link"

  # Metrics to track
  metrics:
    - name: "ledger_api_deprecation_usage_total"
      type: "counter"
      labels: ["endpoint", "version", "consumer"]
      description: "Usage count of deprecated endpoints"

    - name: "ledger_api_version_requests_total"
      type: "counter"
      labels: ["version"]
      description: "Requests per API version"

# Current deprecations (none yet)
deprecations: []