API Migration Guide

This guide helps you migrate your integration from previous API versions to the current parameter-controlled design. The main changes focus on performance optimization through selective data inclusion.

Overview of Changes

The API has evolved from automatically including all available enrichment data to a parameter-controlled system that allows you to request only the data you need.

What Changed

Aspect	Previous Behavior	Current Behavior
ACSC Data	Included by default when available	Requires include=acsc parameter
Enrichment Data	All included automatically	Requires include=enrichment parameter
KEV Data	Included by default	Still included by default ✅
EPSS Data	Included by default	Still included by default ✅
Response Headers	Included quota information	Quota headers removed (except from /usage endpoint)
Performance	Slower due to larger payloads	Optimized for speed and caching

Why These Changes?

1. Performance Optimization: 80%+ cache hit rates with edge caching
2. Bandwidth Efficiency: Smaller payloads when enrichment data isn't needed
3. Selective Data Loading: Get only what you need for your use case
4. Better Caching: Consistent responses enable better CDN caching

Breaking Changes

1. ACSC Data Inclusion

Before (Automatic Inclusion):

# Old behavior - ACSC data included automatically
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

# Response included ACSC array when available
{
  "data": {
    "cve": {
      "id": "CVE-2024-0001",
      "cvss": {...},
      "acsc": [...] // ← Included automatically
    }
  }
}

After (Parameter Required):

# New behavior - ACSC data requires explicit parameter
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc"

# Default request no longer includes ACSC
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

# Response without include=acsc
{
  "data": {
    "cve": {
      "id": "CVE-2024-0001",
      "cvss": {...}
      // No ACSC array unless include=acsc is used
    }
  }
}

2. Quota Headers Removal

Before:

# Old behavior - quota headers in all responses
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

# Response headers included:
# X-Quota-Limit: 30000
# X-Quota-Used: 1523
# X-Quota-Remaining: 28477

After:

# New behavior - quota headers removed for better caching
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

# No quota headers in response
# Use dedicated endpoint for quota information:
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/usage

Migration Steps

Step 1: Audit Your Current Usage

First, identify how your application currently uses the API:

# Check your current requests
grep -r "api.cybersecfeed.com" /your/codebase/

# Look for ACSC data usage
grep -r "\.acsc" /your/codebase/
grep -r "acsc\[" /your/codebase/

Step 2: Update ACSC Data Requests

If your application uses ACSC data, add the include=acsc parameter:

Python Example:

# Before
def get_cve(cve_id):
    response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        headers={"X-API-Key": api_key}
    )
    return response.json()

# After
def get_cve(cve_id, include_acsc=False):
    params = {}
    if include_acsc:
        params['include'] = 'acsc'

    response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        headers={"X-API-Key": api_key},
        params=params
    )
    return response.json()

# Update calls that need ACSC data
cve_data = get_cve("CVE-2024-0001", include_acsc=True)

JavaScript Example:

// Before
async function getCVE(cveId) {
	const response = await fetch(`https://api.cybersecfeed.com/api/v1/cve/${cveId}`, { headers: { 'X-API-Key': apiKey } });
	return await response.json();
}

// After
async function getCVE(cveId, options = {}) {
	const params = new URLSearchParams();
	if (options.includeACSC) {
		params.append('include', 'acsc');
	}

	const url = `https://api.cybersecfeed.com/api/v1/cve/${cveId}`;
	const finalUrl = params.toString() ? `${url}?${params}` : url;

	const response = await fetch(finalUrl, {
		headers: { 'X-API-Key': apiKey },
	});
	return await response.json();
}

// Update calls that need ACSC data
const cveData = await getCVE('CVE-2024-0001', { includeACSC: true });

Step 3: Update Search Queries

If you search for CVEs and need ACSC data in results:

# Before - ACSC included automatically
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?severity_min=7.0&limit=20"

# After - Add include parameter
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?severity_min=7.0&include=acsc&limit=20"

Step 4: Update Quota Monitoring

Replace quota header reading with dedicated endpoint calls:

Before:

def check_quota_from_headers(response):
    quota_limit = int(response.headers.get('X-Quota-Limit', 0))
    quota_used = int(response.headers.get('X-Quota-Used', 0))
    return quota_limit, quota_used

# This no longer works
response = requests.get(url, headers=headers)
limit, used = check_quota_from_headers(response)

After:

def check_quota():
    response = requests.get(
        "https://api.cybersecfeed.com/api/v1/usage",
        headers={"X-API-Key": api_key}
    )
    usage_data = response.json()["data"]["usage"]
    return usage_data["quota"], usage_data["used"]

# Use dedicated endpoint
quota_limit, quota_used = check_quota()

Step 5: Optimize Performance

Take advantage of the new parameter system for better performance:

def get_cve_optimized(cve_id, use_case):
    """Get CVE data optimized for specific use cases"""

    params = {}

    if use_case == "basic_scan":
        # Fast: just core data + KEV + EPSS
        pass  # No include parameters needed

    elif use_case == "regional_threat":
        # Include ACSC for Australian organizations
        params['include'] = 'acsc'

    elif use_case == "complete_intel":
        # Full intelligence picture
        params['include'] = 'acsc,enrichment'

    elif use_case == "risk_score_only":
        # Minimal data for risk calculations
        params['fields'] = 'id,cvss.baseScore,kev,epss.score'

    response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        headers={"X-API-Key": api_key},
        params=params
    )
    return response.json()

# Use case-specific calls
basic_data = get_cve_optimized("CVE-2024-0001", "basic_scan")
intel_data = get_cve_optimized("CVE-2024-0001", "complete_intel")

Migration Patterns

Pattern 1: Conditional ACSC Inclusion

class CyberSecFeedClient:
    def __init__(self, api_key, default_include_acsc=False):
        self.api_key = api_key
        self.default_include_acsc = default_include_acsc

    def get_cve(self, cve_id, include_acsc=None):
        # Use instance default if not specified
        if include_acsc is None:
            include_acsc = self.default_include_acsc

        params = {}
        if include_acsc:
            params['include'] = 'acsc'

        # ... make request

# Regional client that always includes ACSC
au_client = CyberSecFeedClient(api_key, default_include_acsc=True)

# Global client that doesn't include ACSC by default
global_client = CyberSecFeedClient(api_key, default_include_acsc=False)

Pattern 2: Graceful Fallback

def get_cve_with_fallback(cve_id):
    """Try with ACSC first, fallback to basic if needed"""

    try:
        # First try with ACSC data
        response = requests.get(
            f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
            params={'include': 'acsc'},
            headers=headers,
            timeout=5
        )
        return response.json()

    except requests.Timeout:
        # Fallback to faster basic request
        response = requests.get(
            f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
            headers=headers,
            timeout=10
        )
        return response.json()

Pattern 3: Batch Migration

def migrate_batch_requests():
    """Update batch operations to include ACSC when needed"""

    cve_ids = ["CVE-2024-0001", "CVE-2024-0002", "CVE-2024-0003"]

    # Old way (no longer includes ACSC)
    # response = requests.get(f"{base_url}/cves", params={'ids': ','.join(cve_ids)})

    # New way (explicitly include ACSC)
    params = {
        'ids': ','.join(cve_ids),
        'include': 'acsc'
    }
    response = requests.get(f"{base_url}/cves", params=params, headers=headers)
    return response.json()

Testing Your Migration

1. Response Validation

def validate_migration(cve_id):
    """Test that migration preserves expected data"""

    # Get response with new parameter-controlled approach
    response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        params={'include': 'acsc'},
        headers=headers
    )

    data = response.json()["data"]["cve"]

    # Validate expected fields are present
    assert 'id' in data
    assert 'cvss' in data

    # Check ACSC data when expected
    if 'acsc' in data:
        print(f"✅ ACSC data found for {cve_id}")
    else:
        print(f"ℹ️ No ACSC data for {cve_id} (may be expected)")

    return data

2. Performance Comparison

import time

def compare_performance():
    """Compare response times before and after migration"""

    cve_id = "CVE-2024-0001"

    # Test basic request (optimized)
    start = time.time()
    basic_response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        headers=headers
    )
    basic_time = time.time() - start

    # Test with ACSC (legacy equivalent)
    start = time.time()
    acsc_response = requests.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
        params={'include': 'acsc'},
        headers=headers
    )
    acsc_time = time.time() - start

    print(f"Basic request: {basic_time:.3f}s")
    print(f"With ACSC: {acsc_time:.3f}s")
    print(f"Performance gain: {((acsc_time - basic_time) / acsc_time) * 100:.1f}%")

Rollback Plan

If you need to temporarily revert behavior during migration:

class BackwardCompatibleClient:
    """Client that mimics old behavior during migration"""

    def __init__(self, api_key, legacy_mode=True):
        self.api_key = api_key
        self.legacy_mode = legacy_mode

    def get_cve(self, cve_id):
        params = {}

        # In legacy mode, always include ACSC (like old behavior)
        if self.legacy_mode:
            params['include'] = 'acsc'

        response = requests.get(
            f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}",
            params=params,
            headers={"X-API-Key": self.api_key}
        )
        return response.json()

# Use during migration period
client = BackwardCompatibleClient(api_key, legacy_mode=True)

# Switch to optimized mode when ready
client = BackwardCompatibleClient(api_key, legacy_mode=False)

Migration Checklist

Pre-Migration

• Audit current API usage for ACSC data dependencies
• Identify quota monitoring code that reads headers
• Review batch operations and search queries
• Test current integration with a staging environment

During Migration

• Update CVE detail requests to include include=acsc if needed
• Update search/list endpoints with appropriate include parameters
• Replace quota header reading with /usage endpoint calls
• Add error handling for parameter validation
• Test response caching behavior

Post-Migration

• Monitor application performance improvements
• Validate all ACSC-dependent features still work
• Update documentation and team knowledge
• Consider optimizing further with field projection
• Set up monitoring for quota usage via /usage endpoint

Support During Migration

If you encounter issues during migration:

1. Check the troubleshooting guide for common parameter-related errors
2. Use the new /usage endpoint to monitor quota consumption
3. Test with simple requests (without parameters) first
4. Contact support at [email protected] with specific error details

Include in your support request:

• Before/after request examples
• Expected vs actual responses
• Migration timeline and urgency
• Specific use cases for ACSC data

The migration improves API performance significantly while maintaining all functionality through explicit parameter control. Most integrations require minimal changes to add include=acsc where needed.