Sentinel API Deprecation Agent

An API lifecycle management agent for Sentinel that helps you gracefully deprecate and sunset API endpoints.

Features

• RFC-Compliant Headers: Adds standard Deprecation and Sunset (RFC 8594) headers
• Usage Tracking: Prometheus metrics for monitoring deprecated endpoint usage
• Flexible Actions: Warn, redirect, or block deprecated endpoints
• Automatic Redirects: Redirect old endpoints to new versions with query preservation
• Migration Support: Include documentation links in deprecation notices
• Glob Patterns: Match multiple endpoints with glob-style patterns

Installation

Using Cargo

cargo install sentinel-agent-api-deprecation

From Source

git clone https://github.com/raskell-io/sentinel-agent-api-deprecation
cd sentinel-agent-api-deprecation
cargo build --release

Quick Start

1. Create a configuration file api-deprecation.yaml:

endpoints:
  - id: legacy-users-api
    path: /api/v1/users
    methods: [GET, POST]
    status: deprecated
    sunset_at: "2025-06-01T00:00:00Z"
    replacement:
      path: /api/v2/users
    documentation_url: https://docs.example.com/migration
    action:
      type: warn

2. Add to your Sentinel configuration:

agents {
    api-deprecation socket="/tmp/sentinel-api-deprecation.sock"
}

3. Start the agent:

sentinel-agent-api-deprecation -c api-deprecation.yaml

Configuration

Deprecated Endpoints

Each deprecated endpoint supports:

Field	Type	Description
id	string	Unique identifier for the endpoint
path	string	Path pattern (supports globs like /api/v1/*)
methods	list	HTTP methods to match (empty = all)
status	enum	deprecated, scheduled, or removed
deprecated_at	datetime	When the endpoint was deprecated
sunset_at	datetime	When the endpoint will be removed
replacement	object	Replacement endpoint info
documentation_url	string	Link to migration guide
message	string	Custom deprecation message
action	object	What to do when accessed
track_usage	bool	Track usage metrics (default: true)

Actions

Warn (default): Allow the request but add deprecation headers

action:
  type: warn

Redirect: Redirect to the replacement endpoint

action:
  type: redirect
  status_code: 308  # Permanent redirect

Block: Return an error response

action:
  type: block
  status_code: 410  # Gone

Custom: Return a custom response

action:
  type: custom
  status_code: 403
  body: '{"error": "This API version is no longer available"}'
  content_type: application/json

Replacement Info

replacement:
  path: /api/v2/users
  preserve_query: true  # Preserve query string in redirects
  method: POST         # Optional: if the method changed

Global Settings

settings:
  deprecation_header: Deprecation      # Header name
  sunset_header: Sunset                # Header name
  link_header: Link                    # Header name for docs/replacement
  notice_header: X-Deprecation-Notice  # Header for human-readable message
  include_headers: true                # Add headers to responses
  past_sunset_action: warn             # warn, block, or redirect
  log_access: true                     # Log deprecated endpoint access

Response Headers

When an endpoint is deprecated, the following headers are added:

Deprecation: @1704067200
Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Link: <https://docs.example.com/migration>; rel="deprecation", </api/v2/users>; rel="successor-version"
X-Deprecation-Notice: This endpoint (/api/v1/users) is deprecated and will be removed on 2025-06-01. Please migrate to /api/v2/users.

Metrics

The agent exposes Prometheus metrics for monitoring:

Metric	Type	Description
sentinel_api_deprecation_requests_total	counter	Total requests to deprecated endpoints
sentinel_api_deprecation_redirects_total	counter	Total redirects performed
sentinel_api_deprecation_blocked_total	counter	Total blocked requests
sentinel_api_deprecation_days_until_sunset	gauge	Days until endpoint sunset
sentinel_api_deprecation_request_duration_seconds	histogram	Request duration

Enable metrics server:

sentinel-agent-api-deprecation --metrics --metrics-port 9090

CLI Options

sentinel-agent-api-deprecation [OPTIONS]

Options:
  -c, --config <PATH>        Configuration file [default: api-deprecation.yaml]
  -s, --socket <PATH>        Unix socket path [default: /tmp/sentinel-api-deprecation.sock]
  -L, --log-level <LEVEL>    Log level [default: info]
      --print-config         Print default configuration
      --validate             Validate configuration and exit
      --metrics              Enable metrics server
      --metrics-port <PORT>  Metrics server port [default: 9090]
  -h, --help                 Print help
  -V, --version              Print version

Use Cases

Gradual API Migration

Track usage of v1 endpoints while migrating clients to v2:

endpoints:
  - id: users-v1
    path: /api/v1/users
    status: deprecated
    sunset_at: "2025-06-01T00:00:00Z"
    replacement:
      path: /api/v2/users
    action:
      type: warn

Immediate Redirect

Force clients to use the new endpoint:

endpoints:
  - id: old-auth
    path: /auth/login
    status: deprecated
    replacement:
      path: /api/v2/auth/login
      preserve_query: true
    action:
      type: redirect
      status_code: 308

Removed Endpoint

Return 410 Gone for completely removed endpoints:

endpoints:
  - id: legacy-api
    path: /legacy/*
    status: removed
    documentation_url: https://docs.example.com/sunset-notice
    action:
      type: block
      status_code: 410

License

Apache-2.0