API Versioning

OilPriceAPI uses URL-based versioning to ensure backward compatibility while enabling continuous improvements.

Current Version

API Version: v1

Base URL: https://api.oilpriceapi.com/v1

All API endpoints are prefixed with /v1/ to indicate the API version.

Versioning Strategy

Semantic Versioning

We follow semantic versioning principles:

• Major version (v1, v2): Breaking changes that require client updates
• Minor updates: New features, endpoints, or optional parameters (backward compatible)
• Patch updates: Bug fixes and performance improvements

Version Lifecycle

v1 Stability Guarantee

The v1 API is stable and production-ready.

We guarantee:

• No breaking changes to existing endpoints
• Existing parameters will continue to work
• Response structure remains consistent
• New fields may be added (additive changes only)

What We Consider Breaking

• Removing endpoints or parameters
• Changing response field names or types
• Modifying authentication requirements
• Changing error response formats

What We Don't Consider Breaking

• Adding new optional parameters
• Adding new response fields
• Adding new endpoints
• Adding new error codes
• Performance improvements

Deprecation Policy

Deprecation Notice

When an endpoint or feature is deprecated:

1. Announcement: Posted to changelog and sent via email
2. Response Header: X-API-Deprecated: true added
3. Documentation: Marked as deprecated with alternatives
4. Timeline: Minimum 90 days before removal

Example Deprecated Response

HTTP/1.1 200 OK
X-API-Deprecated: true
X-API-Deprecation-Date: 2025-06-01
X-API-Sunset-Date: 2025-09-01

{
  "status": "success",
  "data": { ... },
  "_deprecation": {
    "message": "This endpoint is deprecated. Use /v1/prices/latest instead.",
    "replacement": "/v1/prices/latest",
    "sunset_date": "2025-09-01"
  }
}

Handling Deprecations

1. Monitor for X-API-Deprecated header
2. Check changelog monthly for deprecation notices
3. Plan migration to replacement endpoints
4. Test with replacement before sunset date
5. Contact support if migration is unclear

Migration Guide

Future v2 (Not Yet Announced)

When v2 is released:

1. v1 will enter deprecated phase (12 months support)
2. Migration guide will be published
3. Parallel operation of v1 and v2
4. SDK updates with v2 support

Migration Best Practices

# Good: Explicit version in code
API_VERSION = "v1"
BASE_URL = f"https://api.oilpriceapi.com/{API_VERSION}"

# Better: Configuration-based version
import os
API_VERSION = os.getenv("OILPRICEAPI_VERSION", "v1")
BASE_URL = f"https://api.oilpriceapi.com/{API_VERSION}"

Version Headers

Request Headers

Include version information for better debugging:

X-API-Version: v1
X-Client-Version: 1.4.3
X-SDK-Name: oilpriceapi-python

Response Headers

Every response includes version info:

SDK Version Compatibility

SDKs are designed to work with the current API version. Major SDK versions align with API versions.

Changelog Integration

Stay updated on API changes:

• Changelog: docs.oilpriceapi.com/changelog
• RSS Feed: Coming soon
• Email Updates: Enabled by default for account owners

Support

Questions about versioning or migrations?

• Email: [email protected]
• Documentation: docs.oilpriceapi.com
• Enterprise: Dedicated migration support available

FAQ

How do I know which version I'm using?

Check the URL path. All v1 endpoints start with /v1/:

https://api.oilpriceapi.com/v1/prices/latest

Will v1 be retired?

Not in the foreseeable future. v1 is our current and actively developed API version.

How will I be notified of deprecations?

• Email to account owners (90+ days notice)
• Response header on deprecated endpoints
• Changelog updates
• Dashboard notifications

Can I use multiple API versions?

When v2 is released, yes. You can migrate gradually by updating endpoints one at a time.