Skip to main content

Health Scores

Monitor and improve mock API simulation quality using automated health scoring. Health scores evaluate route coverage, response freshness, error rates, latency performance, and overall reliability, providing actionable recommendations.

Prerequisites​

  • An existing mock simulation with at least one route and response
  • Understanding of basic simulation metrics
  • Some request traffic to the simulation (for trend analysis)

Understanding Health Scores​

The health scoring system evaluates simulations across five dimensions:

Health Score Dimensions​

DimensionMeasuresGood Score
Route CoveragePercentage of routes with mock responses> 90%
Response FreshnessHow recently responses were updated< 30 days
Error RatePercentage of requests returning errors< 5%
Latency PerformanceResponse time consistency and speedP95 < 1000ms
Error DiversityCoverage of different HTTP status codes3+ different codes

Overall Health Score​

Composite score from 0-100 based on weighted dimensions:

  • 90-100: A - Excellent health
  • 80-89: B - Good health with minor issues
  • 70-79: C - Fair health with improvement needed
  • 60-69: D - Poor health, addressing issues recommended
  • 0-59: F - Critical issues requiring attention

Accessing Health Scores​

Dashboard View​

  1. Open simulation dashboard
  2. Look for Health Score card or widget
  3. See current score and grade at a glance

Simulation Health Details​

  1. Open simulation
  2. Click Health or Health Score tab
  3. View comprehensive health report:
    • Current overall score and grade
    • Scores for each dimension
    • Key findings and issues
    • Recommendations
    • Last computed timestamp

Company-Wide Health Summary​

  1. Go to workspace dashboard
  2. Click Health Summary or All Simulations Health
  3. See health scores for all your simulations
  4. Sort and filter by score/grade
  5. Identify simulations needing attention

Health Score Components​

Route Coverage​

Shows percentage of routes with at least one mock response:

Route Coverage: 75%
  - Total routes: 12
  - Routes with responses: 9
  - Uncovered routes: 3

Finding: Missing responses for POST /api/users, DELETE /api/users/:id, PATCH /api/profile
Recommendation: Add mock responses for these routes to improve coverage

Response Freshness​

Measures how recently responses were updated:

Response Freshness: 85%
  - Oldest response: 45 days (GET /api/health)
  - Average age: 18 days
  - Recently updated (< 7 days): 8 routes

Finding: Some responses haven't been updated in 45+ days
Recommendation: Review and refresh outdated responses quarterly

Error Rate​

Tracks percentage of failed requests:

Error Rate: 3.2%
  - Total requests (24h): 1,000
  - Successful: 968
  - Errors: 32
  - Error types: 2 timeouts, 10 validation errors, 20 intentional mocks

Finding: Error rate is within normal bounds
Recommendation: Monitor for spikes in validation errors

Latency Performance​

Evaluates response time metrics:

Latency Performance: 88%
  - P50 (median): 45ms
  - P95 (95th percentile): 250ms
  - P99 (99th percentile): 450ms
  - Slowest route: POST /api/complex (avg 350ms)

Finding: Good overall performance; one route slower than others
Recommendation: Consider reducing simulated delay on POST /api/complex

Error Diversity​

Measures coverage of different HTTP status codes:

Error Diversity: 65%
  - Success responses (2xx): 8 routes
  - Client errors (4xx): 3 routes (insufficient coverage)
  - Server errors (5xx): 1 route
  - Redirects (3xx): 0 routes

Finding: Limited 4xx and 5xx error response definitions
Recommendation: Add 400, 401, 403, 404, 429, and 500 responses

Health History Timeline​

View how health score has changed over time:

  1. Open simulation health details
  2. Click History or Trends tab
  3. See score snapshots over time (up to 100 recent records)

Each history entry shows:

  • Computed timestamp
  • Overall score
  • Dimension scores
  • Key metrics

Trend Chart​

Visualize health score trends:

  1. Open health history
  2. View line chart of score over time
  3. See dimension trends in separate lines (if expanded)
  4. Identify improving or declining dimensions

Trend Analysis​

Interpret trends:

  • Upward trend - Simulation quality improving
  • Flat trend - Stable quality
  • Downward trend - Quality degrading; investigate cause
  • Spikes - Sudden changes; check for recent changes

Refreshing Health Scores​

Recompute health score after making simulation changes:

Manual Refresh​

  1. Open simulation health details
  2. Click Refresh or Recompute Score
  3. Wait for computation to complete
  4. View updated score and findings

Recomputation takes 5-30 seconds depending on simulation size.

Auto-Refresh​

Health scores automatically recompute:

  • When routes are added/removed
  • When responses are modified
  • When response versions are promoted
  • Periodically (every few hours)

When to Manually Refresh​

  • After adding many routes at once
  • After promoting new response versions
  • After fixing validation errors
  • To verify score after making improvements

Finding and Acting on Issues​

Review Findings​

Findings are actionable issues identified by the health system:

  1. Open health score details
  2. Click Findings or Issues section
  3. See list of issues with:
    • Issue title and description
    • Affected routes/responses
    • Severity or impact
    • Recommended action

Generate Fix Suggestions​

Get AI-powered recommendations:

  1. Select a finding
  2. Click Get Suggestion or How to Fix
  3. View suggested action steps
  4. Click on route/response if applicable
  5. Make the recommended change

Example findings:

1. Route Uncovered
   Route: DELETE /api/users/:id
   Impact: Cannot test deletion workflow
   Suggestion: Add mock response for successful deletion (200) or error (404)

2. Outdated Response
   Route: GET /api/config
   Last updated: 62 days ago
   Impact: Consumers may have outdated expectations
   Suggestion: Review configuration format and update response if needed

3. Missing Error Variants
   Route: POST /api/auth/login
   Coverage: Only success (200) response defined
   Suggestion: Add error responses for 401 (invalid credentials) and 429 (rate limited)

4. High Latency
   Route: POST /api/complex-operation
   P95 latency: 1200ms
   Impact: Slow responses may cause timeouts in tests
   Suggestion: Reduce latencyMs configuration or investigate complex logic

5. Validation Failures
   Route: PUT /api/users/:id
   Failure rate: 8% of requests
   Impact: Consumers sending invalid data
   Suggestion: Review validation schema and provide error details in mock response

Health Score Best Practices​

Maintain Healthy Simulations​

  1. Cover all routes - Ensure every route has at least one response
  2. Add error variants - Mock 4xx and 5xx responses
  3. Keep responses fresh - Review and update quarterly
  4. Monitor trends - Check health monthly
  5. Act on findings - Address critical issues promptly

Set Health Targets​

  1. Establish team standards:

    • Minimum score for production-like simulations (e.g., 80+)
    • Maximum uncovered routes allowed (e.g., 10%)
    • Required error response coverage (e.g., 4xx, 5xx, rate limit)

  2. Review health quarterly:

    • Are scores improving?
    • Are recommendations being implemented?
    • Any declining simulations?

Health for Different Contexts​

Development Simulation (Lower standards):

  • Minimum score: 60+
  • May have partial coverage
  • Focus on happy path routes

Staging Simulation (Moderate standards):

  • Minimum score: 75+
  • Should have error variants
  • Recent updates recommended

Production-like Simulation (High standards):

  • Minimum score: 85+
  • Complete route coverage
  • All error scenarios covered
  • Validated against actual API

Troubleshooting​

Score Seems Inaccurate​

  • Refresh the score manually
  • Check that routes were saved properly
  • Verify responses are associated with correct routes
  • Wait for auto-refresh if made recent changes

Health is F but Looks Good​

  • Review the detailed findings
  • Check which dimension is pulling score down
  • Focus on the specific dimension improvement
  • Refresh after making changes

Can't See Health Insights​

  • Ensure simulation has traffic history
  • Health scores improve with usage data
  • Create some test requests to the simulation
  • Wait for next auto-refresh

Score Not Updating​

  • Check when score was last computed
  • Try manual refresh
  • Verify no simulation errors blocking computation
  • Contact support if stuck

API Reference​

Health Score Endpoints​

MethodPathDescription
GET/instances/health-summaryGet health for all instances
GET/instances/:id/healthGet current health score
GET/instances/:id/health/historyGet score history timeline
POST/instances/:id/health/refreshForce recompute health
POST/instances/:id/health/findings/:idx/fixGet fix suggestion

Next Steps​