HATEOAS API Versioning — Evolving Hypermedia APIs Without Breaking Clients

class VersionedApi {
  constructor() {
    this.relations = new Map();
  }
  
  // Register a link relation with version range
  registerRelation(rel, href, minVersion, maxVersion = null) {
    if (!this.relations.has(rel)) {
      this.relations.set(rel, []);
    }
    this.relations.get(rel).push({ href, minVersion, maxVersion });
  }
  
  // Get links for a specific client version
  getLinksForVersion(version) {
    const links = {};
    
    for (const [rel, implementations] of this.relations) {
      const matching = implementations.find(impl =>
        impl.minVersion <= version &&
        (impl.maxVersion === null || version <= impl.maxVersion)
      );
      
      if (matching) {
        links[rel] = { href: matching.href };
      }
    }
    
    return links;
  }
  
  // Add deprecation info to links
  getLinksWithDeprecation(version) {
    const links = {};
    
    for (const [rel, implementations] of this.relations) {
      const active = implementations.find(impl =>
        impl.minVersion <= version &&
        (impl.maxVersion === null || version <= impl.maxVersion)
      );
      
      const deprecated = implementations.find(impl =>
        impl.minVersion <= version &&
        impl.maxVersion !== null &&
        version >= impl.maxVersion - 1
      );
      
      if (active) {
        links[rel] = {
          href: active.href,
          ...(deprecated ? { deprecation: true, sunset: deprecated.maxVersion } : {}),
        };
      }
    }
    
    return links;
  }
}

// Usage
const api = new VersionedApi();

// v1: original endpoint
api.registerRelation('dt:scan', '/v1/devices/{id}/scan', 1.0, 1.9);
// v1.5: new endpoint added (both work)
api.registerRelation('dt:deep-scan', '/v2/devices/{id}/deep-scan', 1.5);
api.registerRelation('dt:scan', '/v2/devices/{id}/scan', 2.0);

const express = require('express');
const app = express();

// Deprecation tracking
const deprecatedRelations = new Map();

function deprecateRelation(rel, sunsetVersion, migrationUrl) {
  deprecatedRelations.set(rel, { sunsetVersion, migrationUrl });
}

function addDeprecationHeaders(res, requestVersion, links) {
  for (const [rel, link] of Object.entries(links)) {
    if (link.deprecation) {
      res.set(`Link-Deprecation-${rel}`, `sunset=${link.sunset}; migration=${link.migrationUrl}`);
    }
  }
}

app.get('/devices/:id', (req, res) => {
  const clientVersion = parseFloat(req.headers['accept-version'] || '1.0');
  const device = getDevice(req.params.id);
  
  const links = {
    self: { href: `/devices/${device.id}` },
    threats: { href: `/devices/${device.id}/threats` },
  };
  
  // Version-dependent links
  if (clientVersion < 2.0) {
    links['dt:scan'] = {
      href: `/devices/${device.id}/scan`,
      deprecation: true,
      sunset: '2026-09-01',
      migrationUrl: '/docs/migration-v2',
    };
  }
  
  if (clientVersion >= 1.5) {
    links['dt:deep-scan'] = {
      href: `/devices/${device.id}/deep-scan`,
    };
  }
  
  // Add Sunset header for deprecated features
  addDeprecationHeaders(res, clientVersion, links);
  
  res.json({ ...device, _links: links });
});

// Version negotiation
app.use((req, res, next) => {
  const version = req.headers['accept-version'];
  
  // Deprecation warning header
  if (version && parseFloat(version) < 2.0) {
    res.set('Warning', '299 - "This API version is deprecated. Upgrade to v2."');
    res.set('Sunset', 'Sat, 01 Sep 2026 00:00:00 GMT');
  }
  
  next();
});

class VersionAwareClient {
  constructor(rootUrl, clientVersion = 2.0) {
    this.rootUrl = rootUrl;
    this.clientVersion = clientVersion;
    this.supportedRelations = new Set([
      'self', 'devices', 'threats', 'scans',
      'dt:scan', 'dt:deep-scan', 'dt:quarantine',
    ]);
  }
  
  async fetch(url) {
    const res = await fetch(url, {
      headers: {
        'Accept-version': String(this.clientVersion),
        'Accept': 'application/hal+json',
      },
    });
    
    // Check deprecation warnings
    const warning = res.headers.get('Warning');
    if (warning && this.onDeprecationWarning) {
      this.onDeprecationWarning(warning);
    }
    
    // Check Sunset header
    const sunset = res.headers.get('Sunset');
    if (sunset) {
      console.log(`API sunset date: ${sunset}`);
    }
    
    return res.json();
  }
  
  async navigate() {
    const root = await this.fetch(this.rootUrl);
    const links = root._links || {};
    
    // Find links we understand
    const available = Object.keys(links)
      .filter(rel => this.supportedRelations.has(rel));
    
    console.log('Available known links:', available);
    
    // Use the most appropriate version of a link
    const scanLink = links['dt:deep-scan'] || links['dt:scan'];
    if (scanLink) {
      console.log('Using scan link:', scanLink.href);
      await this.fetch(scanLink.href);
    }
    
    // Check for link deprecation
    for (const [rel, link] of Object.entries(links)) {
      if (link.deprecation) {
        console.warn(`Link '${rel}' deprecated, sunset: ${link.sunset}`);
        console.warn(`Migration: ${link.migrationUrl}`);
      }
    }
  }
}