HATEOAS JSON HAL — Hypermedia Application Language for REST APIs

{
  "_links": {
    "self": { "href": "/devices/1" },
    "threats": { "href": "/devices/1/threats" },
    "scans": { "href": "/devices/1/scans" },
    "config": { "href": "/devices/1/config" },
    "curies": [
      {
        "name": "dt",
        "href": "https://docs.dodatech.com/rels/{rel}",
        "templated": true
      }
    ],
    "dt:quarantine": { "href": "/devices/1/quarantine" },
    "dt:analyze": { "href": "/devices/1/analyze" }
  },
  "_embedded": {
    "threats": [
      {
        "_links": {
          "self": { "href": "/threats/101" }
        },
        "threatId": "101",
        "name": "Ransomware-X"
      }
    ]
  },
  "deviceId": "1",
  "name": "Office-PC",
  "os": "Windows 11",
  "status": "active"
}

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

// HAL helper
function hal(resource, links, embedded = {}) {
  const result = { ...resource, _links: {} };
  
  for (const [rel, href] of Object.entries(links)) {
    if (typeof href === 'object') {
      result._links[rel] = href;
    } else {
      result._links[rel] = { href };
    }
  }
  
  if (Object.keys(embedded).length > 0) {
    result._embedded = embedded;
  }
  
  return result;
}

// Device endpoint with HAL
app.get('/devices/:id', (req, res) => {
  const device = getDevice(req.params.id);
  const threats = getThreatsForDevice(req.params.id);
  
  const response = hal(
    { ...device },
    {
      self: `/devices/${device.id}`,
      threats: `/devices/${device.id}/threats`,
      scans: `/devices/${device.id}/scans`,
      config: `/devices/${device.id}/config`,
      'dt:quarantine': `/devices/${device.id}/quarantine`,
      curies: [{
        name: 'dt',
        href: 'https://docs.dodatech.com/rels/{rel}',
        templated: true,
      }],
    },
    {
      threats: threats.map(t => hal(
        { ...t },
        { self: `/threats/${t.id}` }
      )),
    }
  );
  
  res.json(response);
});

// Collection with HAL
app.get('/devices', (req, res) => {
  const devices = getAllDevices();
  
  const response = hal(
    { total: devices.length },
    {
      self: '/devices',
      next: devices.length > 20 ? '/devices?page=2' : null,
    },
    {
      items: devices.map(d => hal(
        { ...d },
        { self: `/devices/${d.id}` }
      )),
    }
  );
  
  res.json(response);
});

class HalClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.cache = new Map();
  }
  
  async fetch(url) {
    if (this.cache.has(url)) {
      return this.cache.get(url);
    }
    
    const response = await fetch(url);
    const resource = await response.json();
    this.cache.set(url, resource);
    return resource;
  }
  
  async followLink(resource, rel) {
    const link = resource._links[rel];
    if (!link) {
      throw new Error(`Link '${rel}' not found`);
    }
    return this.fetch(link.href);
  }
  
  async navigate() {
    // Start at root
    const root = await this.fetch('/api');
    console.log('Available actions:', Object.keys(root._links));
    
    // Follow to devices
    const devices = await this.followLink(root, 'devices');
    console.log('Devices:', devices._embedded.items.length);
    
    // Follow to first device's threats
    const firstDevice = devices._embedded.items[0];
    const threats = await this.followLink(firstDevice, 'threats');
    console.log('Threats:', threats);
    
    // Follow to quarantine action
    await this.followLink(firstDevice, 'dt:quarantine');
    console.log('Device quarantined');
  }
}

// Usage
const client = new HalClient('https://api.dodatech.com');
await client.navigate();