Skip to main content

API Versioning and Compatibility

This document explains the versioning scheme for the Instinct API and provides guidance on maintaining compatibility with future updates.

API Versioning Scheme​

The Instinct API follows semantic versioning principles to indicate the level of changes in each release:

  • Major version changes (e.g., v1.0.0 to v2.0.0): Introduce breaking changes that require code updates.
  • Minor version changes (e.g., v1.0.0 to v1.1.0): Add new features in a backward-compatible manner.
  • Patch version changes (e.g., v1.0.0 to v1.0.1): Introduce bug fixes and minor improvements.

All API endpoints currently use the same version, which is embedded in the headset firmware. The current version of the API can be obtained by calling the version endpoint:

curl http://localhost:42069/system/version

Response:

{
  "success": true,
  "data": {
    "api": "1.0.0",
    "firmware": "1.0.2",
    "hardware": "rev2"
  }
}

Backward Compatibility Policy​

Instinct is committed to maintaining backward compatibility within the same major version:

  • Endpoints will not be removed within the same major version.
  • Request parameters required in previous versions will continue to be supported.
  • Response fields present in previous versions will continue to be included.
  • Enumeration values will not be removed or changed within the same major version.

New features may be added in minor versions:

  • New optional request parameters may be added
  • New response fields may be added
  • New enumeration values may be added

Breaking Changes​

The following are considered breaking changes and will only be introduced with a major version increment:

  • Removing an endpoint
  • Removing a required request parameter
  • Removing fields from response objects
  • Changing the data type of a field
  • Changing the behavior of an endpoint significantly
  • Adding new required parameters that don't have defaults

Deprecation Process​

Before removing any feature or making a breaking change, we follow a deprecation process:

  1. The feature is marked as deprecated in the documentation.
  2. Warning headers or messages are added in responses using the deprecated feature.
  3. The deprecation is maintained for at least one full major version cycle.
  4. After the deprecation period, the feature may be removed in the next major version.

Best Practices for API Consumers​

To ensure your application remains compatible with future API versions:

1. Use the Appropriate API Version​

Always be aware of which API version you're using and refer to the documentation for that specific version.

2. Ignore Unknown Fields​

When processing API responses, design your code to ignore fields that your application doesn't recognize. This ensures your code doesn't break when we add new fields to responses.

3. Check for Success and Handle Errors​

Always check the success field in responses and properly handle errors:

fetch('http://localhost:42069/stream/streams')
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      // Process data
    } else {
      // Handle error
      console.error(`Error: ${data.error.code} - ${data.error.message}`);
    }
  });

4. Use Feature Detection​

For features that might not be available in all versions, use feature detection:

async function supportsFeature(featureName) {
  try {
    const response = await fetch('http://localhost:42069/system/features');
    const data = await response.json();

    if (data.success && data.data.supported_features) {
      return data.data.supported_features.includes(featureName);
    }
    return false;
  } catch (error) {
    console.error('Error checking feature support:', error);
    return false;
  }
}

// Usage
async function useFeatureIfAvailable() {
  if (await supportsFeature('advanced_filtering')) {
    // Use advanced filtering
  } else {
    // Fall back to basic filtering
  }
}

5. Plan for Version Migrations​

When a new major version is released, review the migration guide and update your code accordingly. It's recommended to:

  • Test your application against the new version in a development environment
  • Update your codebase to support both the old and new versions during transition
  • Gradually roll out the update to your users

Firmware Updates and API Compatibility​

The Instinct API is bundled with the headset firmware. When you update the headset firmware:

  1. The API version may change
  2. New features may be added
  3. Deprecated features may be removed (in major version updates)

To ensure a smooth update process:

  • Always check the release notes before updating firmware
  • Test your application with the new firmware version before deploying to production
  • Keep your application up to date with the latest API changes

Next Steps​