Skip to main content

API Versioning

How we handle API versions, backward compatibility, and changes.

Current Version​

PropertyValue
API Version2.8.0
StatusStable
Base URLhttps://api.web3identity.com

Versioning Strategy​

Semantic Versioning​

We follow Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes, no breaking changes
  │     └──────── New features, backward compatible
  └────────────── Breaking changes

Current: v2.8.0

  • 2 = Major version (breaking changes from v1)
  • 8 = Minor version (new features added)
  • 0 = Patch version (bug fixes)

Version in Responses​

Every response includes the API version:

X-API-Version: 2.8.0
const res = await fetch('https://api.web3identity.com/api/health');
console.log(res.headers.get('X-API-Version')); // "2.8.0"

Stability Commitment​

What We Promise​

CategoryCommitment
Endpoint URLsWon't change without major version bump
Response fieldsExisting fields won't be removed
Error codesError codes remain stable
Free tier100 calls/day minimum guaranteed

What May Change​

CategoryType of Change
New fieldsAdded to responses (non-breaking)
New endpointsAdded regularly
PerformanceResponse times may improve
New error codesAdditional error types may be added

No URL Versioning​

We chose not to include versions in URLs:

✅ https://api.web3identity.com/api/ens/vitalik.eth
❌ https://api.web3identity.com/v2/api/ens/vitalik.eth

Why:

  • Simpler URLs
  • Easier to use and remember
  • No need to update URLs when upgrading
  • Breaking changes are rare

Deprecation Policy​

When we need to make breaking changes:

Timeline​

PhaseDurationWhat Happens
AnnouncementDay 0Blog post, changelog, email
Deprecation30 daysOld behavior works, warnings in response
Migration60 daysBoth old and new work
Removal90 daysOld behavior removed

Deprecation Warnings​

Deprecated features include a warning header:

X-Deprecation-Warning: This endpoint will be removed on 2026-05-01. Use /api/v2/new-endpoint instead.
const res = await fetch(url);
const warning = res.headers.get('X-Deprecation-Warning');
if (warning) {
  console.warn('API Deprecation:', warning);
}

Breaking vs Non-Breaking Changes​

Non-Breaking (Safe)​

These changes don't require action:

// Adding new fields to responses
// Before
{ "name": "vitalik.eth", "address": "0x..." }

// After (new field added - non-breaking)
{ "name": "vitalik.eth", "address": "0x...", "avatar": "https://..." }

Your code still works — just ignore fields you don't need.

Breaking (Requires Action)​

These changes require updating your code:

// Removing a field
// Before
{ "name": "vitalik.eth", "owner": "0x..." }

// After (field removed - BREAKING)
{ "name": "vitalik.eth" }  // 'owner' gone!

// Changing field type
// Before
{ "balance": "1000000000000000000" }  // string

// After (type changed - BREAKING)
{ "balance": 1000000000000000000 }    // number

Migration Guide​

Handling New Fields​

// ✅ Safe: Use optional chaining
const avatar = profile.avatar ?? null;
const twitter = profile.records?.['com.twitter'] ?? '';

// ✅ Safe: Destructure with defaults
const { name, address, avatar = null } = profile;

Handling Deprecations​

// ✅ Check for deprecation warnings
async function fetchWithDeprecationCheck(url) {
  const res = await fetch(url);
  
  const warning = res.headers.get('X-Deprecation-Warning');
  if (warning) {
    // Log for your team to address
    console.warn(`[DEPRECATION] ${url}: ${warning}`);
    
    // Optionally send to monitoring
    sendToMonitoring('api_deprecation', { url, warning });
  }
  
  return res.json();
}

Changelog​

Track all changes in our Changelog.

Recent Changes​

VersionDateTypeDescription
2.8.02026-02-08FeatureFull modularization, 966 endpoints
2.7.02026-02-08FeatureCache warming, analytics
2.6.02026-02-08FeatureSmart-fetch with fallbacks
2.5.02026-02-07Feature1000+ endpoints milestone

SDK Version Compatibility​

SDK VersionAPI VersionStatus
1.1.x2.x✅ Compatible
1.0.x2.x✅ Compatible

The SDK handles version differences automatically:

import { ATVClient } from '@atv-eth/x402-sdk';

const client = new ATVClient();
// SDK automatically adapts to API version

Questions?​