API Versioning & Changelog

Understand API versioning, backward compatibility, and track changes across versions.

Versioning Strategy

Current Version

Latest API Version: v1 Base URL: https://api.torvussecurity.com/v1

Release Date: January 15, 2025 Status: ✅ Stable (production-ready)

Version Format

Major Version in URL:

https://api.torvussecurity.com/v1/vaults
                              ^^
                              Major version

Why URL Versioning?

Clear and explicit (no hidden version header)
Easy to test different versions side-by-side
Compatible with all HTTP clients
Industry standard (used by Stripe, GitHub, Twitter, etc.)

Version Scheme:

Major version (v1, v2, v3): Breaking changes
Minor version (implicit): New features, backward-compatible
Patch version (implicit): Bug fixes, backward-compatible

Example Timeline:

v1.0.0 (Jan 2025)  → Initial release
v1.1.0 (Mar 2025)  → New endpoints added (backward-compatible)
v1.2.0 (Jun 2025)  → New fields added (backward-compatible)
v1.2.1 (Jul 2025)  → Bug fix (backward-compatible)
v2.0.0 (Jan 2026)  → Breaking changes (new major version)

Backward Compatibility

What We Promise

Backward-Compatible Changes (won't break your code):

✅ Adding new API endpoints
✅ Adding new optional request parameters
✅ Adding new properties to API responses
✅ Adding new webhook events
✅ Adding new error codes (with existing error still returned)
✅ Changing error messages (never parse error messages!)
✅ Increasing rate limits
✅ Bug fixes that make API more permissive

Breaking Changes (require major version bump):

❌ Removing or renaming API endpoints
❌ Removing or renaming request parameters
❌ Removing or renaming response properties
❌ Changing response data types (string → number, etc.)
❌ Adding new required request parameters
❌ Changing authentication methods
❌ Decreasing rate limits
❌ Changing HTTP status codes
❌ Bug fixes that make API more restrictive

Your Responsibilities

Write Resilient Code:

✅ Ignore unknown fields:

// Good: Ignore new fields you don't recognize
const { id, name } = vault;

// Bad: Throw error on unknown fields
if (Object.keys(vault).some(key => !knownFields.includes(key))) {
  throw new Error('Unknown field');
}

✅ Don't depend on field order:

// Good: Access by name
const name = vault.name;

// Bad: Access by position
const name = Object.values(vault)[1];

✅ Handle new enum values gracefully:

// Good: Handle unknown status
switch (vault.status) {
  case 'active':
    // ...
    break;
  case 'archived':
    // ...
    break;
  default:
    // New status we don't recognize yet - handle gracefully
    console.warn(`Unknown vault status: ${vault.status}`);
    break;
}

// Bad: Crash on unknown status
if (!['active', 'archived'].includes(vault.status)) {
  throw new Error('Invalid status');
}

✅ Don't parse error messages:

// Good: Use error codes
if (error.code === 'vault_not_found') {
  // Handle vault not found
}

// Bad: Parse error message (fragile, messages can change)
if (error.message.includes('not found')) {
  // This breaks if we change message wording
}

Deprecation Policy

Deprecation Process

Timeline:

Announcement (T+0): Feature marked as deprecated in docs and API responses
Warning Period (T+6 months): Deprecation warnings in API responses
Removal (T+12 months): Feature removed in next major version

Example:

Jan 2025: Feature X deprecated (v1.5)
  → Announced in changelog
  → Documented as deprecated
  → API returns `X-Deprecated-Endpoint: true` header

Jul 2025: Warning period (v1.8)
  → API returns 299 Warning header
  → Email notifications to users still using deprecated feature

Jan 2026: Removed in v2.0
  → Feature no longer available in v2
  → v1 still available for 6 more months

Deprecation Headers

Deprecated Endpoints Return Special Headers:

GET /v1/legacy-endpoint HTTP/1.1

HTTP/1.1 200 OK
X-Deprecated-Endpoint: true
X-Deprecated-Since: 2025-01-15
X-Deprecated-Replacement: /v1/new-endpoint
Deprecation: Sun, 15 Jan 2026 00:00:00 GMT
Warning: 299 - "This endpoint is deprecated and will be removed on 2026-01-15. Use /v1/new-endpoint instead."

Check for Deprecation:

const response = await fetch('https://api.torvussecurity.com/v1/endpoint');

if (response.headers.get('X-Deprecated-Endpoint')) {
  const replacement = response.headers.get('X-Deprecated-Replacement');
  console.warn(`Deprecated endpoint! Use ${replacement} instead.`);
}

Migration Guides

We Provide:

Detailed migration guides for breaking changes
Code examples showing before/after
Automated migration scripts (when possible)
Dedicated support during migration period

Example Migration Guide (v1 → v2):

## Migrating from v1 to v2

### Breaking Change: `status` field renamed to `state`

Before (v1):
```javascript
const vault = await torvus.vaults.get('vault_123');
console.log(vault.status); // "active"

After (v2):

const vault = await torvus.vaults.get('vault_123');
console.log(vault.state); // "active"

Migration Script:

// Update all code references
// Old: vault.status
// New: vault.state

---

## Version Support

### Supported Versions

| Version | Status | Released | EOL Date | Support Level |
|---------|--------|----------|----------|---------------|
| **v1** | ✅ Current | Jan 15, 2025 | TBD | Full support |
| v2 | 🚧 Planned | Jan 2026 | TBD | Not yet released |

**Support Levels**:
- **Full Support**: Active development, new features, bug fixes, security updates
- **Maintenance**: Bug fixes and security updates only (no new features)
- **Deprecated**: Security updates only (no bug fixes or features)
- **End of Life (EOL)**: No support (upgrade required)

### Version Lifecycle

**Typical Lifecycle**:

v1 Release (Jan 2025) ↓ v1 Full Support (Jan 2025 - Dec 2025) ↓ v2 Release (Jan 2026) ↓ v1 Maintenance Mode (Jan 2026 - Jun 2026)

v2 is now recommended
v1 receives bug fixes and security updates ↓ v1 Deprecated (Jul 2026 - Dec 2026)
v1 receives security updates only
Deprecation warnings in responses ↓ v1 End of Life (Jan 2027)
v1 no longer available
All users must migrate to v2

**Minimum Support Period**: 12 months after successor release

---

## Changelog

### v1.3.0 (Planned - October 2025)

**New Features**:
- ✨ Bulk operations API endpoints
  - `POST /v1/vaults/batch` - Create multiple vaults in one request
  - `POST /v1/recipients/batch` - Create multiple recipients in one request
- ✨ Webhook event filtering
  - Filter webhook events by type when registering webhook
  - Reduces unnecessary webhook calls

**Improvements**:
- 🚀 Rate limits increased for Business and Enterprise plans
  - Business: 1,000 → 2,500 requests/hour
  - Enterprise: 5,000 → 10,000 requests/hour
- 🚀 Faster response times for list endpoints (avg 50ms → 30ms)

**Bug Fixes**:
- 🐛 Fixed: Pagination cursor sometimes skips results
- 🐛 Fixed: Webhook signature verification fails for payloads over 1MB

---

### v1.2.0 (August 2025)

**New Features**:
- ✨ `GET /v1/vaults/{id}/activity` - Retrieve vault activity logs
- ✨ `GET /v1/documents/{id}/versions` - Retrieve document version history
- ✨ New webhook events:
  - `document.version.created` - Fired when new document version uploaded
  - `recipient.verification.completed` - Fired when recipient completes identity verification

**Improvements**:
- 🚀 Added field selection support (e.g., `?fields=id,name,created_at`)
- 🚀 Added sorting support for list endpoints (e.g., `?sort=created_at:desc`)
- 📄 Improved error messages with more context

**Bug Fixes**:
- 🐛 Fixed: `updated_at` timestamp not updated when vault settings changed
- 🐛 Fixed: Search endpoint returns HTTP 500 for some special characters

**Deprecations**:
- ⚠️ `GET /v1/search` deprecated in favor of `/v1/vaults/search` (more specific)
  - Will be removed in v2.0 (January 2026)

---

### v1.1.0 (May 2025)

**New Features**:
- ✨ `POST /v1/vaults/{id}/check-in` - Manual check-in endpoint
- ✨ `GET /v1/vaults/{id}/check-in-status` - Get next check-in deadline
- ✨ New webhook events:
  - `vault.check_in.missed` - Fired when check-in deadline passes
  - `vault.check_in.grace_period_started` - Fired when grace period begins

**Improvements**:
- 🚀 Added ETag support for conditional requests (HTTP 304 responses)
- 🚀 Added `X-Request-ID` header to all responses (for debugging)
- 📄 API responses now include `api_version` field

**Bug Fixes**:
- 🐛 Fixed: Date fields return inconsistent timezone (now always UTC)
- 🐛 Fixed: List endpoint returns 500 error when `limit` exceeds 1000

---

### v1.0.1 (March 2025)

**Bug Fixes**:
- 🐛 Fixed: Webhook signatures fail verification for non-ASCII characters
- 🐛 Fixed: Rate limit headers missing from some responses
- 🐛 Fixed: `created_at` field missing from recipient objects

**Security**:
- 🔒 Improved API key validation (reject keys with invalid format immediately)

---

### v1.0.0 (January 15, 2025)

**Initial Release**:

**Authentication**:
- 🔑 API key authentication (Bearer token)

**Endpoints**:
- Vaults: Create, read, update, delete, list
- Documents: Upload, read, update, delete, list
- Recipients: Create, read, update, delete, list
- Policies: Create, read, update, delete, list
- Check-ins: Get status

**Features**:
- ✨ Pagination (page-based and cursor-based)
- ✨ Filtering and search
- ✨ Webhooks (10 event types)
- ✨ Rate limiting (varies by plan)
- ✨ Idempotency keys
- ✨ Request retries (automatic for 5xx errors)

---

## Breaking Changes (Upcoming)

### v2.0 (Planned - January 2026)

**Breaking Changes**:

**1. Field Renames**:
- `status` → `state` (all resources)
- `created_at` → `created` (all resources)
- `updated_at` → `updated` (all resources)

**2. Response Structure Changes**:
```javascript
// v1 (current)
{
  "vaults": [...],
  "total": 100,
  "page": 1,
  "per_page": 25
}

// v2 (planned)
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 25
  }
}

3. Error Format Changes:

// v1 (current)
{
  "error": "Validation failed",
  "errors": [
    { "field": "name", "message": "Name is required" }
  ]
}

// v2 (planned)
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      { "field": "name", "code": "required", "message": "Name is required" }
    ]
  }
}

4. Removed Endpoints:

GET /v1/search (deprecated in v1.2) → Use /v1/vaults/search or /v1/documents/search
GET /v1/legacy-endpoint (deprecated in v1.5) → Use /v1/new-endpoint

5. Authentication Changes:

API key format changed: tvs_v1_... → tvs_v2_...
v1 keys will continue to work with v1 API until EOL

Migration Guide: Detailed guide will be published 6 months before v2 release.

Staying Updated

Changelog Notifications

Subscribe to Updates:

Email Newsletter: changelog@torvussecurity.com (monthly digest)
RSS Feed: https://api.torvussecurity.com/changelog.xml
API Changelog Header: All responses include X-API-Version header

Automatic Notifications:

// Check API version in response
const response = await fetch('https://api.torvussecurity.com/v1/vaults');
const apiVersion = response.headers.get('X-API-Version');

if (apiVersion !== expectedVersion) {
  console.warn('API version changed! Check changelog.');
}

API Version Discovery

Get Current Version:

curl https://api.torvussecurity.com/version

{
  "api_version": "1.2.0",
  "current_version": "v1",
  "latest_version": "v1",
  "supported_versions": ["v1"],
  "deprecated_versions": [],
  "changelog_url": "https://docs.torvussecurity.com/api/changelog"
}

Deprecation Warnings in Dashboard

Torvus Dashboard Alerts:

Notifications when using deprecated endpoints
List of deprecated features you're currently using
Migration guides and recommended actions

Migration Support

Tools

API Version Checker:

# Check which deprecated features you're using
curl https://api.torvussecurity.com/v1/deprecated-usage \
  -H "Authorization: Bearer $API_KEY"

{
  "deprecated_endpoints_used": [
    {
      "endpoint": "GET /v1/search",
      "usage_count": 1234,
      "last_used": "2025-10-01T15:30:00Z",
      "replacement": "GET /v1/vaults/search",
      "removal_date": "2026-01-15"
    }
  ]
}

Migration Script Generator:

# Generate migration script for your codebase
torvus-migrate generate --from v1 --to v2 --language javascript

# Output: migration-v1-to-v2.js
# - Automated find-and-replace rules
# - Manual review required for complex changes

Support

Migration Assistance (Enterprise customers):

Dedicated migration support engineer
Code review and migration planning
Custom migration scripts
Extended v1 support (up to 6 months beyond EOL)

Community Support:

Migration guides and examples
Community forum discussions
Office hours (monthly Q&A sessions)

Best Practices

Pin Your API Version

Always Use Explicit Version in URL:

// Good: Explicit version
const baseUrl = 'https://api.torvussecurity.com/v1';

// Bad: No version (breaks when default version changes)
const baseUrl = 'https://api.torvussecurity.com'; // Don't do this

Test New Versions Early

Use Test Environment:

// Test v2 before it becomes default
const baseUrlV2 = 'https://api.torvussecurity.com/v2'; // Test environment

// Run integration tests against v2
await runTests(baseUrlV2);

Monitor Deprecation Headers

Set Up Alerts:

async function callAPI(endpoint, options) {
  const response = await fetch(endpoint, options);

  // Check for deprecation
  if (response.headers.get('X-Deprecated-Endpoint')) {
    alertDevelopers({
      endpoint,
      deprecatedSince: response.headers.get('X-Deprecated-Since'),
      replacement: response.headers.get('X-Deprecated-Replacement')
    });
  }

  return response;
}

Plan Migrations Early

Don't Wait Until Last Minute:

Review changelog monthly
Plan migrations 3-6 months before EOL
Test migrations in staging environment
Migrate in phases (start with non-critical features)

FAQ

How often do you release new API versions?

Rarely. Major versions (v1 → v2) only when breaking changes are necessary. We aim for 12-18 month cycles for major versions.

Minor versions (v1.1, v1.2, etc.) released every 2-3 months with new features (backward-compatible).

Will my API keys work with new versions?

Same major version: Yes. v1 API keys work with all v1.x versions.

Different major version: No. v2 requires new API keys (different format: tvs_v2_...).

You can generate v2 API keys before migrating and use them to test v2 while still using v1 in production.

How long do you support old versions?

Minimum 12 months after successor release.

Example: v2 releases January 2026 → v1 supported until at least January 2027.

Enterprise customers can negotiate extended support (additional 6-12 months).

Can I use multiple versions simultaneously?

Yes. You can use v1 for some features and v2 for others during migration period.

const torvusV1 = new TorvusClient({ apiKey: v1Key, version: 'v1' });
const torvusV2 = new TorvusClient({ apiKey: v2Key, version: 'v2' });

// Use v1 for existing features
const vaults = await torvusV1.vaults.list();

// Use v2 for new features
const advancedSearch = await torvusV2.vaults.search({ query: '...' });

What if I find a bug in the changelog?

Report it: changelog@torvussecurity.com

We maintain high accuracy in changelogs but mistakes happen. We'll correct errors and notify subscribers.

Do you follow semantic versioning?

Partially. We use semantic versioning principles:

Major version (v1, v2): Breaking changes
Minor version (v1.1, v1.2): New features, backward-compatible
Patch version (v1.2.1, v1.2.2): Bug fixes, backward-compatible

But we only expose major version in URL (minor/patch versions are implicit).

API Reference: Complete API documentation
API Best Practices: Performance and security best practices
Error Handling: Error codes and handling
Rate Limiting: Rate limit details

Last Updated: October 8, 2025

Versioning Strategy​

Current Version​

Version Format​

Backward Compatibility​

What We Promise​

Your Responsibilities​

Deprecation Policy​

Deprecation Process​

Deprecation Headers​

Migration Guides​

Migration Script:​

Staying Updated​

Changelog Notifications​

API Version Discovery​

Deprecation Warnings in Dashboard​

Migration Support​

Tools​

Support​

Best Practices​

Pin Your API Version​

Test New Versions Early​

Monitor Deprecation Headers​

Plan Migrations Early​

FAQ​

How often do you release new API versions?​

Will my API keys work with new versions?​

How long do you support old versions?​

Can I use multiple versions simultaneously?​

What if I find a bug in the changelog?​

Do you follow semantic versioning?​

Related Guides​