Release Policy

Versioning

MarketCheck APIs follow semantic versioning principles to ensure clear and predictable updates. Each version consists of three segments: MAJOR.MINOR.PATCH.

• MAJOR: Introduces incompatible changes, requiring client updates
• MINOR: Adds functionality in a backward-compatible manner
• PATCH: Backward-compatible bug fixes

Routing

To access a specific API version, include the version number in a special request header:

x-version: v4.0.0

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/listing/car/3FTTW8M34RRA21879-b4178158-1a02',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'x-version': 'v4.3.0'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Version Auto-Upgrade

Within the same major version, API requests are automatically upgraded to the latest compatible version to ensure you receive the most stable and feature-complete experience:

• Compatible Upgrades: Minor and patch versions within the same major version
  • v4.2.1 → v4.2.3 (patch upgrade)
  • v4.2.1 → v4.3.0 (minor upgrade)
  • v4.2.1 → v4.4.2 (minor + patch upgrade)
• Non-Compatible: Major version changes require explicit client updates
  • v4.3.0 will not auto-upgrade to v5.1.0
  • If v4.x.x is no longer available, an error is returned

Response Headers

The following headers are included in every API response to help you understand version handling and debug routing issues:

Release Cadence

Release Type

Release Timeline

1. Announcement
   • Email notification with details on changes, deprecations, and migration guidelines
   • New version available for testing as a non-default option
2. Transition Period
   • For minor/patch releases: maximum 10 days
     • For some minor releases, the transition period may be skipped at MarketCheck’s discretion if the changes are non-disruptive and fully backward-compatible
   • For major releases: minimum 30 days. During this time, both the previous and new versions will be available
3. Default Version Change
   • After the transition period, the new version becomes the default
   • All requests without a version header, or with an older compatible version, will be routed to the latest default version
4. Removal of Previous Version (Major Releases Only)
   • For major releases, the previous version is permanently removed after the transition period. Clients must update their implementations to the new version to continue accessing the API

Deprecation

MarketCheck APIs may deprecate resources such as endpoints, query parameters, or response fields.

Deprecation Process

• A resource is marked as deprecated in a release when it is scheduled for removal
• The deprecation date and sunset date are clearly defined and communicated as part of that release’s changelog and documentation
• Deprecated resources continue to function during the transition period, allowing clients ample time to migrate

Deprecation Response Headers

When accessing a deprecated resource, the API includes the following headers in the response:

These headers provide clear guidance on the lifecycle of deprecated resources, helping clients plan migrations effectively.

Best Practices

• Monitor Your Integration
  • Regularly check for deprecation warnings in response headers
  • Subscribe to API notifications for advance notice of changes
  • Set up alerts to detect deprecation headers in your application logs
• Plan Ahead
  • Review the deprecation schedule and sunset dates
  • Prioritize migration of critical resources well before sunset dates
  • Test new versions in a staging environment before production deployment

See Also

• API Versioning - Version management
• Getting Support - Support channels and resources