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

System	Environment	Base URL
Application Submission APIs (LOS)	Demo	`https://loc.demo.kendra.lendfoundry.com/v1/darbaan`
Active Loan Servicing APIs (LMS)	Demo	`https://api.demo.lms.lendfoundry.com/v1`

Versioning Policy

Non-Breaking Changes

Definition: Changes that don't require client code modifications

Change Type	Example	Impact
✅ New endpoints	`POST /v1/new-feature`	None
✅ New optional fields	Adding `optional_field` to response	None
✅ New error codes	Adding `NEW_ERROR_CODE`	None
✅ Performance improvements	Faster response times	Positive
✅ Documentation updates	Clarified descriptions	None

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

Breaking Changes

Definition: Changes that require client code modifications

Change Type	Example	Impact
❌ Remove endpoints	Removing `DELETE /v1/old-endpoint`	Breaks clients
❌ Remove required fields	Removing `required_field`	Breaks validation
❌ Change field types	`id` from string to integer	Breaks parsing
❌ Rename fields	`loan_id` → `loanId`	Breaks mapping
❌ Change auth method	API Key → OAuth	Breaks auth
❌ Change error format	New error response structure	Breaks handling

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

Stage	Description	Duration
Active	Current version in production use	Ongoing
Deprecated	Still functional, migration recommended	6 months
Retired	No longer available	Permanent

Version Support Timeline

Version	Status	Deprecation Date	Sunset Date	Support Level
`v1`	✅ Active	—	—	Full support
`v2`	🔮 Planned	—	—	Not yet available

Deprecation Policy

Standard Deprecation Period

Duration: 6 months

Deprecation Process

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

Notification Channels

Channel	Timing
📧 Email	Sent to registered technical contacts
📢 API Response Headers	`Deprecation` header on deprecated endpoints
📝 Changelog	Published in API changelog
🔔 Status Page	Posted on status.lendfoundry.com

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

Header	Description
`Deprecation`	Indicates endpoint is deprecated
`Sunset`	Date when endpoint will be retired
`Link`	URL to successor endpoint

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

Test	Description
✅ All endpoints tested	Every endpoint used in production
✅ Error handling verified	All error codes handled properly
✅ Authentication works	Auth method compatible
✅ Data mapping correct	Request/response field mapping
✅ Performance acceptable	Response times within SLA
✅ Edge cases handled	Unusual inputs and states

Best Practices

For API Consumers

✅ DO	❌ DON'T
Monitor deprecation notices	Ignore deprecation emails
Plan migrations early	Wait until last minute
Test in sandbox first	Deploy untested code
Keep code flexible (version configurable)	Hardcode version URLs
Subscribe to changelog	Miss version announcements

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:

Channel	Content
📧 Email	Migration guide, timeline, breaking changes
📢 Blog post	Feature announcements, benefits
📝 Changelog	Technical details, examples
🔔 Status page	Availability and timelines

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: sales@lendfoundry.com
Subject: "API Version Question - [Your Company]"

✅
Understanding Versioning?
Explore the Workflow Guides for implementation examples.