API Migrations

When to Use This

API migrations are needed when:

APIs are deprecated with deadlines
Breaking changes require code updates
New API versions offer better performance/features
Security improvements in new APIs
Vendor requires migration

Common examples:

REST API endpoint changes
Authentication method updates
Cloud provider API updates
Kubernetes API version migrations
Internal library updates

Basic Pattern

1. Understand the Migration

Before using Tidra:

Read the API migration guide
Identify all changes needed
Note breaking changes
Find code examples

2. Map Old to New

Document:

Old endpoints → new endpoints
Old methods → new methods
Old parameters → new parameters
Authentication changes
Response format changes

3. Write Your Description

Include:

What's changing (endpoints, methods, auth)
How to update (show examples)
Where to look (which files, patterns)
Edge cases and exceptions

Example: REST API Endpoint Migration

Goal

Migrate from deprecated API v1 to API v2.

Migration Details

Old API:

POST https://api.example.com/v1/users
Headers: X-API-Key: YOUR_KEY

New API:

POST https://api.example.com/v2/users
Headers: Authorization: Bearer YOUR_TOKEN

Description

Migrate API calls from v1 to v2:

1. Update API endpoints:
   - Change all instances of "api.example.com/v1/" to "api.example.com/v2/"

2. Update authentication:
   - Old: headers = {"X-API-Key": api_key}
   - New: headers = {"Authorization": f"Bearer {api_token}"}

3. Look for these patterns in:
   - Python: requests.post(), requests.get()
   - JavaScript: fetch(), axios.post(), axios.get()
   - Any file making HTTP calls to api.example.com

4. Update import/configuration:
   - Update API_BASE_URL constants
   - Update any hardcoded endpoints

What to Check

✅ All v1 references changed to v2
✅ Authentication header updated
✅ Constants/config updated
✅ No missed API calls

Example: Kubernetes API Version Update

Goal

Update Kubernetes manifests from v1beta1 to v1.

Description

Update Kubernetes API versions in all YAML manifests:

Find deployments using:
apiVersion: apps/v1beta1
kind: Deployment

Change to:
apiVersion: apps/v1
kind: Deployment

Also look for:
- apiVersion: extensions/v1beta1 (Ingress) → networking.k8s.io/v1
- apiVersion: batch/v1beta1 (CronJob) → batch/v1

Files to check:
- k8s/*.yaml
- kubernetes/*.yaml
- deploy/*.yaml
- .kube/*.yaml

What to Check

✅ All v1beta1 updated to v1
✅ API groups updated (extensions → networking)
✅ YAML syntax still valid
✅ Required fields added for v1 (like selector)

Example: Authentication Migration

Goal

Migrate from API key to OAuth 2.0.

Description

Update authentication from API keys to OAuth 2.0:

Old pattern (remove this):

headers = {"X-API-Key": settings.API_KEY}
response = requests.get(url, headers=headers)

New pattern (replace with this):

from auth import get_oauth_token

headers = {"Authorization": f"Bearer {get_oauth_token()}"}
response = requests.get(url, headers=headers)

Find all uses of X-API-Key header
Replace with Authorization Bearer pattern
Add import for get_oauth_token if not present
Look in all .py files that make API calls

Don't change:

Internal API calls (api.internal.company.com)
Third-party APIs that still use API keys

What to Check

✅ API key references removed
✅ OAuth pattern added
✅ Import statements added
✅ Internal APIs left unchanged

Example: Method Deprecation

Goal

Replace deprecated method calls with new methods.

Description

Replace deprecated logger.log() with logger.info():

Old pattern:
logger.log("Starting process")
logger.log(f"Processing {item}")

New pattern:
logger.info("Starting process")
logger.info(f"Processing {item}")

Apply to all .py files in:
- src/
- lib/
- services/

Don't change:
- logger.error()
- logger.warning()
- logger.debug()
- Third-party code in vendor/

What to Check

✅ All logger.log() changed to logger.info()
✅ Other log levels untouched
✅ Vendor code unchanged
✅ No syntax errors introduced

Advanced: Complex Migration

Goal

Migrate from old client library to new one with different API.

Description

Migrate from old_sdk to new_sdk:

1. Update imports:
   from old_sdk import Client → from new_sdk import APIClient

2. Update client initialization:
   Old: client = Client(api_key=key)
   New: client = APIClient(credentials={'api_key': key})

3. Update method calls:
   Old: client.get_user(user_id)
   New: client.users.get(user_id)

   Old: client.create_user(data)
   New: client.users.create(data)

4. Update error handling:
   Old: except old_sdk.APIError as e:
   New: except new_sdk.exceptions.APIException as e:

5. Look in files that:
   - Import old_sdk
   - Have "Client(" initialization
   - Make API calls

Refer to migration guide: https://docs.new-sdk.com/migration

What to Check

✅ Imports updated
✅ Client initialization updated
✅ Method calls updated
✅ Error handling updated
✅ Code still logically correct

Tips for Success

Provide Code Examples

Show exact before/after code, not just descriptions.

Reference Documentation

Link to official migration guides: "Follow the migration steps at [link]"

Test Thoroughly

API migrations can break functionality. Review carefully and test:

Generated code is syntactically correct
Logic is preserved
No missing imports

Batch by Language

Do Python repos separately from JavaScript repos. Different code patterns require different descriptions.

Handle Errors Gracefully

Mention how to handle errors in the new API if they've changed.

Common Mistakes

Assuming Simple Find-Replace

API migrations often involve:

Import changes
Initialization changes
Parameter reordering
Error handling updates

Don't just replace the endpoint URL.

Missing Error Cases

New APIs may have different error responses. Update error handling too.

Forgetting Configuration

Don't just update code. Update:

Config files
Environment variables
Documentation
Tests

Not Testing First

Always test on a few repos before scaling to all.

Validation Checklist

Before creating PRs:

Next Steps

Dependency Updates - Update package versions
Configuration Updates - Update configs
Best Practices - General tips