Skip to main content

Mock API Testing Guide

Audience: Developer, Admin
Page Type: How-To

Overview​

COS ships with a mock KPI API (tools/mock-kpi-api/) that simulates an external data source. Use it to test pull integrations without needing a real BI tool, data warehouse, or monitoring system.

The mock API:

  • Supports all 5 auth modes (NONE, BEARER_TOKEN, BASIC_AUTH, API_KEY_HEADER, API_KEY_QUERY)
  • Returns realistic KPI data (revenue, NPS, churn, etc.)
  • Provides multiple response formats (flat, nested, timeseries, paginated, multi-metric)
  • Simulates error scenarios (timeout, 500, rate limit)

Quick Start​

cd tools/mock-kpi-api
npm install
npm start
# → http://localhost:4444

For development with auto-reload:

npm run dev

Authentication​

All /api/* endpoints require authentication. Use one of the following methods:

Bearer Token​

curl -H "Authorization: Bearer mock-token-2024" \
  http://localhost:4444/api/metrics/revenue

Basic Auth​

curl -u "cosuser:cospass123" \
  http://localhost:4444/api/metrics/revenue

API Key (Header)​

curl -H "X-API-Key: mock-api-key-xyz" \
  http://localhost:4444/api/metrics/revenue

API Key (Query Parameter)​

curl "http://localhost:4444/api/metrics/revenue?api_key=mock-api-key-xyz"

No Auth​

Set AUTH_REQUIRED=false environment variable when starting the server:

AUTH_REQUIRED=false npm start

Default Credentials​

ModeCredentialValue
Bearer TokenTokenmock-token-2024
Basic AuthUsernamecosuser
Basic AuthPasswordcospass123
API KeyKeymock-api-key-xyz

Override via environment variables: BEARER_TOKEN, BASIC_USER, BASIC_PASS, API_KEY.

Endpoints​

Flat Format — GET /api/metrics/:name​

The simplest format. Returns a single metric value.

curl -H "Authorization: Bearer mock-token-2024" \
  http://localhost:4444/api/metrics/revenue

Response:

{
  "metric": "revenue",
  "value": 1250000,
  "target": 1100000,
  "forecast": 1180000,
  "unit": "USD",
  "achievementRate": 113.6,
  "period": "2026-03",
  "timestamp": "2026-03-06T10:00:00.000Z"
}

COS Response Mapping:

{ "actual": "$.value", "target": "$.target", "forecast": "$.forecast" }

Nested Format — GET /api/metrics/:name/detailed​

Values are nested inside a data.metrics object.

curl -H "Authorization: Bearer mock-token-2024" \
  http://localhost:4444/api/metrics/nps/detailed

Response:

{
  "status": "success",
  "data": {
    "kpiName": "Net Promoter Score",
    "description": "Customer satisfaction score",
    "metrics": {
      "current": 72.5,
      "target": 75.0,
      "forecast": 73.8,
      "previousPeriod": 68.2,
      "achievementRate": 96.7
    },
    "metadata": {
      "unit": "score",
      "period": "2026-03",
      "collectedAt": "2026-03-06T10:00:00.000Z",
      "source": "mock-kpi-api"
    }
  }
}

COS Response Mapping:

{ "actual": "$.data.metrics.current", "target": "$.data.metrics.target", "forecast": "$.data.metrics.forecast" }

Timeseries Format — GET /api/metrics/:name/timeseries​

Returns an array of historical data points.

curl -H "Authorization: Bearer mock-token-2024" \
  "http://localhost:4444/api/metrics/revenue/timeseries?months=3"

Response:

{
  "metric": "revenue",
  "period": "2026-03",
  "count": 3,
  "series": [
    { "period": "2026-01", "periodStart": "2026-01-01T...", "periodEnd": "2026-01-31T...", "target": 1100000, "value": 980000, "unit": "USD" },
    { "period": "2026-02", "periodStart": "2026-02-01T...", "periodEnd": "2026-02-28T...", "target": 1150000, "value": 1120000, "unit": "USD" },
    { "period": "2026-03", "periodStart": "2026-03-01T...", "periodEnd": "2026-03-31T...", "target": 1200000, "value": 1250000, "unit": "USD" }
  ]
}

COS Response Mapping (latest value):

{ "actual": "$.series[-1:].value", "target": "$.series[-1:].target" }

Paginated Format — GET /api/metrics/:name/paginated​

Simulates a paginated API with page and per_page query params.

curl -H "X-API-Key: mock-api-key-xyz" \
  "http://localhost:4444/api/metrics/revenue/paginated?page=1&per_page=3"

Response:

{
  "pagination": {
    "page": 1,
    "perPage": 3,
    "total": 24,
    "totalPages": 8,
    "hasNext": true
  },
  "results": [
    { "period": "2024-04", "measurement": 1050000, "target": 1100000, "unit": "USD" },
    { "period": "2024-05", "measurement": 1080000, "target": 1100000, "unit": "USD" },
    { "period": "2024-06", "measurement": 1120000, "target": 1150000, "unit": "USD" }
  ]
}

COS Response Mapping:

{ "actual": "$.results[0].measurement", "target": "$.results[0].target" }

Dashboard Summary — GET /api/dashboard/summary​

All metrics in a single response.

curl -H "Authorization: Bearer mock-token-2024" \
  http://localhost:4444/api/dashboard/summary

Response:

{
  "status": "success",
  "period": "2026-03",
  "metricsCount": 8,
  "kpis": {
    "revenue": { "displayName": "Gelir", "actual": 1250000, "target": 1100000, ... },
    "nps": { "displayName": "Net Promoter Score", "actual": 72.5, "target": 75.0, ... },
    "customer-count": { ... },
    ...
  }
}

COS Response Mapping (for revenue):

{ "actual": "$.kpis.revenue.actual", "target": "$.kpis.revenue.target" }

Error Scenarios​

Test how COS handles various error conditions:

EndpointBehavior
GET /api/error/timeoutResponds after 10 seconds (tests timeout handling)
GET /api/error/500Returns HTTP 500 Internal Server Error
GET /api/error/rate-limitReturns HTTP 429 Too Many Requests

Available Metrics​

NameDescriptionValue Range
revenueMonthly revenue800K – 1.5M USD
customer-countActive customers4,000 – 6,500
npsNet Promoter Score35 – 85
churn-rateMonthly churn rate1% – 8%
employee-satisfactionEmployee satisfaction55% – 95%
uptimeSystem uptime95% – 99.99%
conversion-rateWebsite conversion1% – 12%
response-timeAPI response time50 – 500 ms

Any custom name also works (e.g., /api/metrics/my-custom-kpi) — returns random values.

COS Integration Setup Example​

To test with the mock API in COS:

1. Create Integration Endpoint​

FieldValue
NameMock KPI API
Base URLhttp://localhost:4444
Auth TypeBEARER_TOKEN
Credentials{ "token": "mock-token-2024" }

2. Create KPI Binding​

FieldValue
Path Suffix/api/metrics/revenue
HTTP MethodGET
Response Mapping{ "actual": "$.value", "target": "$.target" }
Cron Expression0 */6 * * * (every 6 hours)

3. Test (Dry Run)​

Click the Test button to verify the integration. You should see:

  • HTTP Status: 200
  • Extracted values: { actual: 1250000, target: 1100000 }

Environment Variables​

VariableDefaultDescription
PORT4444Server port
BEARER_TOKENmock-token-2024Expected Bearer token
BASIC_USERcosuserBasic auth username
BASIC_PASScospass123Basic auth password
API_KEYmock-api-key-xyzExpected API key
AUTH_REQUIREDtrueSet to false to disable auth

See also​