https://github.com/orca-scan/express-deprecator
Drop deprecated API traffic
https://github.com/orca-scan/express-deprecator
express rest-api
Last synced: 3 months ago
JSON representation
Drop deprecated API traffic
- Host: GitHub
- URL: https://github.com/orca-scan/express-deprecator
- Owner: orca-scan
- License: mit
- Created: 2025-06-20T09:01:32.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-21T20:31:20.000Z (about 1 year ago)
- Last Synced: 2025-06-21T20:34:10.593Z (about 1 year ago)
- Topics: express, rest-api
- Language: JavaScript
- Homepage: https://orcascan.com
- Size: 154 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# express-deprecator
[](https://github.com/orca-scan/express-deprecator/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/express-deprecator)
[](https://github.com/orca-scan/express-deprecator/blob/master/LICENSE)
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
```bash
npm install express-deprecator
```
## Usage
```js
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:
```json
[
{
"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:
```bash
POST /api/submit
Content-Type: application/json
{
"lib": {
"version": "0.0.0"
}
}
```
It’s automatically blocked with:
```bash
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:
```js
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](LICENSE) © Orca Scan - a [barcode app](https://orcascan.com) with simple [barcode tracking APIs](https://orcascan.com/guides?tag=for-developers).