express-deprecator

Drop deprecated API traffic - cleanly, safely, and without legacy routes.

Why? over time, APIs collect old clients, outdated apps, and unsupported versions. express-deprecator helps you phase them out without bloating your app logic.

Features

• No routes needed – matches requests before your logic runs
• Fast + lightweight – no dependencies
• Match on method, url, headers, query, or body
• Regex support – use "/^v1\./" to match patterns
• Not a security layer – built for hygiene, not defense
• Keeps your codebase clean – no more if (version === '0.0.0')

Install

npm install express-deprecator

Usage

const express = require('express');
const expressDeprecator = require('express-deprecator');
const app = express();

app.use(express.json());
app.use(expressDeprecator()); // auto-loads ./deprecations.json

Example rule

Block outdated client versions in request body:

[
  {
    "description": "Deprecate old client (v0.0.0)",
    "method": "POST",
    "url": "/api/submit",
    "body": {
      "lib.version": "0.0.0"
    },
    "status": 426,
    "response": {
      "error": "This version of the client is no longer supported",
      "upgrade": "https://example.com/docs/v2"
    }
  }
]

When a request like this is received:

POST /api/submit
Content-Type: application/json

{
  "lib": {
    "version": "0.0.0"
  }
}

It’s automatically blocked with:

HTTP/1.1 426 Upgrade Required
Content-Type: application/json

{
  "error": "This version of the client is no longer supported",
  "upgrade": "https://example.com/docs/v2"
}

Rule syntax

• Match on any combination of:
  • method: "GET", "POST", etc
  • url: exact path or regex (e.g. "/^\/api\//")
  • headers: header values (supports regex)
  • query: supports nested JSON keys strings (e.g. "payload.device.version")
  • body: supports nested keys in dot notation
• Regex matches must be strings wrapped in /.../
• By default, unmatched requests are passed to your routes
• Matched requests are ended early with the given status and response

What it’s not for

This is not intended to be used as a Web Application Firewall, authentication or security layer. Use it to keep your API maintainable, not to protect it from abuse.

Why not just use code?

You could do this in a route:

if (req.body?.lib?.version === '0.0.0') {
  return res.status(426).json({ error: 'Deprecated version' });
}

But that logic sticks around forever. express-deprecator lets you:

• manage deprecations in a JSON file (not source code)
• remove rules once traffic fades
• keep your API routes lean and focused

License

MIT License © Orca Scan - a barcode app with simple barcode tracking APIs.