Downtime

An OpenAPI-based API endpoint monitoring tool that checks the health of your API endpoints and sends alerts when status changes occur.

Features

• OpenAPI Spec Parsing: Automatically discovers API endpoints from your OpenAPI specification
• Scheduled Health Checks: Monitor endpoints at regular intervals
• Flexible Alerting: Get notified via console or Slack when endpoints change status
• Request Throttling: Control concurrency with configurable request limits
• State Management: Track endpoint status changes over time
• Customizable Status Detection: Define custom logic for determining endpoint health

Installation

npm i -D dowwntime

Quick Start

Create a dowwntime.config.ts file in your project root:

import { ConsoleAlert, defineConfig } from "dowwntime";

export default defineConfig({
  openapiSpecUrl: "https://example.com/api/openapi.json",
  concurrency: 10,
  timeoutMs: 5000,
  storagePath: "./storage.tmp",
  maxSpaceUsageBytes: 262144 * 0.1,
  alerts: [new ConsoleAlert()],
});

Run the health check:

npx dowwntime

Configuration Options

openapiSpecUrl (required)

The URL or file path to your OpenAPI specification. Can be:

• A remote URL: https://registry.scalar.com/@scalar/apis/galaxy?format=yaml
• A local file path: ./openapi.json

alerts (required)

Array of alert handlers to notify when endpoint status changes. Built-in options:

ConsoleAlert

Logs status changes to the console.

import { ConsoleAlert, defineConfig } from "dowwntime";

export default defineConfig({
  openapiSpecUrl: "...",
  alerts: [new ConsoleAlert()],
});

Output example:

[ALERT - UP] Path: /api/health is UP (145ms).
[ALERT - DOWN] Path: /api/data is DOWN (5000ms).
[ALERT - DEGRADED] Path: /api/status is DEGRADED (4200ms).

SlackAlert

Sends formatted messages to a Slack channel via a webhook.

import { SlackAlert, defineConfig } from "dowwntime";

export default defineConfig({
  openapiSpecUrl: "...",
  alerts: [new SlackAlert("https://hooks.slack.com/services/YOUR/WEBHOOK/URL")],
});

Slack messages include:

• Status indicator: ✅ (UP), ❌ (DOWN), ⚠️ (DEGRADED)
• Endpoint path: The API path that changed status
• Full URL: Clickable link to the tested endpoint
• Response time: Duration in milliseconds
• Color coding: Green for UP, red for DOWN, yellow for DEGRADED

To set up a Slack webhook:

1. Go to your Slack workspace's App Directory
2. Search for "Incoming Webhooks"
3. Click "Add to Slack" and select your target channel
4. Copy the webhook URL
5. Add it to your dowwntime.config.ts or pass as an environment variable

concurrency (optional, default: 5)

Maximum number of concurrent requests. Controls how many endpoints are tested simultaneously.

concurrency: 10,

timeoutMs (optional, default: 5000)

Request timeout in milliseconds. If an endpoint doesn't respond within this time, it's marked as DOWN.

timeoutMs: 5000,

storagePath (optional, default: "./storage.tmp")

Path where historical state data is stored. Used to detect status changes between runs.

storagePath: "./storage.tmp",

maxSpaceUsageBytes (optional, default: 262144 * 0.95)

Maximum storage size in bytes. Older entries are removed when this limit is exceeded.

maxSpaceUsageBytes: 262144 * 0.1,

baseUrl (optional)

Override the base URL from the OpenAPI spec. Useful for testing different environments.

baseUrl: "https://staging.example.com",

getExampleValue (optional)

Provide custom example values for path and query parameters. Useful when parameters don't have defaults in the spec.

getExampleValue: (paramName: string, path: string) => {
  if (paramName === "userId") {
    return "12345";
  }
  return undefined;
};

getStatus (optional)

Define custom logic for determining endpoint health based on status code and response time.

getStatus: (statusCode: number, path: string, durationMs: number) => {
  if (statusCode >= 200 && statusCode < 300) {
    if (path === "/api/health" && durationMs > 1000) {
      return "degraded";
    }
    return "up";
  }
  if (statusCode === 429) {
    // Rate limit - mark as degraded instead of down
    return "degraded";
  }
  return "down";
};

Usage in GitHub Actions

Use the provided workflow to automatically check your API endpoints on a schedule.

Setup: Create an Orphan Branch

An orphan branch keeps monitoring history separate from your main codebase:

# Create a new orphan branch (contains no history)
git switch --orphan dowwntime

# Clear the working directory
git rm -rf .

# Create a minimal .gitkeep file
touch .gitkeep
git add .gitkeep

# Commit the orphan branch
git commit -m "Initial commit"

# Push to remote
git push origin dowwntime

# Switch back to main
git checkout main

The orphan branch will contain the storage.tmp file with monitoring history and the monitoring results, keeping your main branch clean.

Workflow Configuration

Create .github/workflows/dowwntime.yml in your repository. Take a look here for a working example.

How It Works

1. Schedule: The workflow runs every 5 minutes (configurable via cron syntax)
2. Config Fetch: Pulls the latest dowwntime.config.ts from your main branch
3. Health Check: Runs monitoring against all endpoints
4. Results Storage: Saves results to storage.tmp (history is maintained on the orphan branch)
5. Alerts: Sends notifications to configured alert handlers (e.g., Slack)
6. Status Tracking: Commits results to the orphan branch for historical tracking

Using Environment Variables

For sensitive data like Slack webhook URLs, use GitHub Secrets:

1. Go to Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Add SLACK_WEBHOOK_URL with your webhook URL

Update your config to use the secret:

import { SlackAlert, defineConfig } from "dowwntime";

export default defineConfig({
  openapiSpecUrl: "...",
  alerts: [new SlackAlert(process.env.SLACK_WEBHOOK_URL!)],
});

License

MIT