API Versioning

Oproto uses URL-based versioning to ensure API stability while allowing for evolution.

Current Version

The current stable API version is v1.

https://api.oproto.io/v1/companies

---

Version Lifecycle

Stage	Description	Support
Preview	New features for early access	Limited, may change
Stable	Production-ready	Full support
Deprecated	Superseded by newer version	Maintenance only
Sunset	End of life	No support

---

Deprecation Policy

When a new API version is released:

1. Announcement — Deprecation notice published (minimum 12 months before sunset)
2. Migration Period — Both versions supported in parallel
3. Sunset Warning — Deprecated version returns warning headers
4. Sunset — Deprecated version returns errors

Deprecation Headers

Deprecated endpoints include warning headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.oproto.io/v2/companies>; rel="successor-version"

Header	Description
Deprecation	Indicates the endpoint is deprecated
Sunset	Date when the endpoint will stop working
Link	URL of the replacement endpoint

---

Breaking vs Non-Breaking Changes

Non-Breaking Changes (No Version Bump)

These changes are made to existing versions:

• Adding new endpoints
• Adding optional request parameters
• Adding new response fields
• Adding new enum values (when documented as extensible)
• Bug fixes that don't change documented behavior

Breaking Changes (New Version)

These changes require a new API version:

• Removing or renaming endpoints
• Removing or renaming request/response fields
• Changing field types or formats
• Changing authentication requirements
• Changing error response formats
• Removing enum values

---

Migration Guide

When migrating to a new API version:

1. Review the Changelog

Check the release notes for breaking changes and new features.

2. Update Your Base URL

// Before
const API_BASE = 'https://api.oproto.io/v1';

// After
const API_BASE = 'https://api.oproto.io/v2';

3. Update Request/Response Handling

Adjust your code for any changed field names or structures:

// v1 response
{
  "company_name": "Acme Corp"
}

// v2 response
{
  "name": "Acme Corp"
}

4. Test Thoroughly

• Run your test suite against the new version
• Test edge cases and error handling
• Verify webhook payloads if applicable

5. Deploy Gradually

Consider a phased rollout:

const API_VERSION = featureFlag('use_api_v2') ? 'v2' : 'v1';
const API_BASE = `https://api.oproto.io/${API_VERSION}`;

---

Version Support Matrix

Version	Status	Released	Sunset Date
v1	Stable	—	—

---

Preview Features

Preview features are available for early testing but may change:

# Access preview features with header
curl -X GET "https://api.oproto.io/v1/companies" \
  -H "Authorization: Bearer {token}" \
  -H "X-API-Preview: 2024-01"

warning

Preview features are not covered by our stability guarantees. Use in production at your own risk.

---

Getting Notified

Stay informed about API changes:

• Subscribe to our Developer Blog
• Watch our GitHub repository
• Monitor deprecation headers in your API responses