Versioning

📘

Long-Term Integration Stability

This document outlines LendFoundry's API versioning strategy, deprecation policy, and migration guidelines. Understanding versioning is critical for long-term integration stability.

LendFoundry is committed to providing stable APIs while continuously improving the platform. Our versioning strategy balances innovation with backward compatibility.

Versioning Approach

LendFoundry uses URI-based versioning for API endpoints.

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#f9fafb', 'clusterBorder': '#2563eb', 'primaryColor': '#2563eb', 'primaryTextColor': '#ffffff', 'titleColor': '#000000', 'lineColor': '#374151'}, 'flowchart': {'padding': 25, 'nodeSpacing': 45, 'rankSpacing': 50}}}%%
flowchart LR
    subgraph URL[🌐 URL Structure]
        A[Base URL] --> B[Version] --> C[Endpoint]
    end
    
    style A fill:#2563eb,stroke:#1e40af,color:#fff
    style B fill:#059669,stroke:#047857,color:#fff
    style C fill:#2563eb,stroke:#1e40af,color:#fff

URL Format

https://api.lendfoundry.com/v{version}/{endpoint}

Examples

https://api.demo.lms.lendfoundry.com/v1/loan-management/search/LN-2024-001/details
https://loc.demo.kendra.lendfoundry.com/v1/darbaan/back-office/rest/api/list-applications

Current Version

Active Version: v1

Base URLs

Versioning Policy

Non-Breaking Changes

Definition: Changes that don't require client code modifications

Policy: Non-breaking changes are deployed to the current version immediately without version bump.

Breaking Changes

Definition: Changes that require client code modifications

Policy: Breaking changes result in a new major version (e.g., v2).

Version Lifecycle

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#f9fafb', 'clusterBorder': '#2563eb', 'primaryColor': '#2563eb', 'primaryTextColor': '#ffffff', 'titleColor': '#000000', 'lineColor': '#374151'}, 'flowchart': {'padding': 25, 'nodeSpacing': 45, 'rankSpacing': 50}}}%%
flowchart TB
    subgraph LIFECYCLE[📋 Version Lifecycle]
        A[✅ Active] --> B[⚠️ Deprecated]
        B --> C[❌ Retired]
    end
    
    style A fill:#059669,stroke:#047857,color:#fff
    style B fill:#d97706,stroke:#b45309,color:#fff
    style C fill:#374151,stroke:#1f2937,color:#fff

Version Support Timeline

Deprecation Policy

Standard Deprecation Period

Duration: 6 months

Deprecation Process

1. Deprecation Notice — Email sent to technical contacts
2. Deprecation Period — 6 months to migrate
3. Sunset — Deprecated version retired

Notification Channels

Deprecation Headers

When an endpoint is deprecated, responses include deprecation headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 15 Jun 2026 00:00:00 GMT
Link: <https://api.lendfoundry.com/v2/loans>; rel="successor-version"
Content-Type: application/json

Migration Guidelines

When to Migrate

Migrate when:

• ✅ New version offers features you need
• ✅ Current version is deprecated
• ✅ Security improvements in new version
• ✅ Performance improvements in new version

Don't migrate if:

• ❌ Current version meets all needs
• ❌ Migration effort exceeds benefits
• ❌ New version has incompatible requirements

Migration Process

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#f9fafb', 'clusterBorder': '#2563eb', 'primaryColor': '#2563eb', 'primaryTextColor': '#ffffff', 'titleColor': '#000000', 'lineColor': '#374151'}, 'flowchart': {'padding': 25, 'nodeSpacing': 45, 'rankSpacing': 50}}}%%
flowchart LR
    subgraph MIGRATE[🔄 Migration Process]
        A[📖 Review] --> B[💻 Update]
        B --> C[🧪 Test]
        C --> D[🚀 Deploy]
        D --> E[📊 Monitor]
    end
    
    style A fill:#2563eb,stroke:#1e40af,color:#fff
    style B fill:#2563eb,stroke:#1e40af,color:#fff
    style C fill:#d97706,stroke:#b45309,color:#fff
    style D fill:#059669,stroke:#047857,color:#fff
    style E fill:#2563eb,stroke:#1e40af,color:#fff

Steps:

• Review — Read migration guide and breaking changes
• Update — Modify code to use new version
• Test — Thoroughly test in sandbox environment
• Deploy — Deploy to production
• Monitor — Watch for errors and performance issues

Parallel Version Support

Support both versions during migration:

import os

class LendFoundryClient:
    """Client supporting multiple API versions."""
    
    def __init__(self, version='v1'):
        self.version = version
        self.base_url = f"https://api.demo.lms.lendfoundry.com/{version}"
    
    def get_loan(self, loan_id):
        """Get loan details (version-aware)."""
        if self.version == 'v2':
            # v2 uses different endpoint structure
            endpoint = f"/loans/{loan_id}"
        else:
            # v1 endpoint structure
            endpoint = f"/loan-management/search/{loan_id}/details"
        
        return requests.get(
            f"{self.base_url}{endpoint}",
            headers=self.headers
        )

# Usage - easy version switching
client_v1 = LendFoundryClient(version='v1')
client_v2 = LendFoundryClient(version='v2')

# Gradual migration with feature flag
use_v2 = os.getenv('USE_API_V2', 'false') == 'true'
client = LendFoundryClient(version='v2' if use_v2 else 'v1')

Migration Testing Checklist

Best Practices

For API Consumers

Version Detection

Check API version from response headers:

import os
import requests

# Make version configurable
API_VERSION = os.getenv('LENDFOUNDRY_API_VERSION', 'v1')
base_url = f"https://api.demo.lms.lendfoundry.com/{API_VERSION}"

# Check version in response
response = requests.get(f"{base_url}/some-endpoint", headers=headers)
api_version = response.headers.get('API-Version', 'v1')
print(f"API Version: {api_version}")

Version Announcements

New Version Release

When a new version is released, you'll be notified through:

FAQ

Q: Can I use multiple versions simultaneously?

A: Yes. You can call both v1 and v2 endpoints from the same application. However, we recommend migrating fully to avoid complexity.

Q: What happens if I don't migrate before sunset?

A: Deprecated versions return 410 Gone after the sunset date. Plan migration well in advance.

{
  "error": {
    "code": "VERSION_RETIRED",
    "message": "API version v1 has been retired. Please upgrade to v2.",
    "migration_guide": "https://docs.lendfoundry.com/migration/v1-to-v2"
  }
}

Q: How do I know which version to use?

A: Use the latest stable version unless you have specific requirements for an older version.

Q: Are there version-specific features?

A: Yes. New features are added to the latest version. Older versions may not have access to new features.

Q: Will there be a v2?

A: Future versions will be released as needed. Each version follows the same deprecation policy with 6 months notice.

Support

Questions about versioning?

• Email: [email protected]
• Subject: "API Version Question - [Your Company]"

✅

Understanding Versioning?

Explore the Workflow Guides for implementation examples.