Evergreen API

An API for Evergreen built on Javascript and Cloudflare Workers with hybrid caching implementation.

🚀 Features

• Hybrid Caching System: 2-tier caching (Memory + KV) with 12-hour TTL
• Performance Optimized: Reduces KV reads to stay within free tier limits
• Comprehensive Testing: Automated validation of API functionality and caching
• Security Focused: Regular security audits and dependency updates
• Production Ready: Robust error handling and monitoring

API Requirements

• Public endpoints do not require authentication.
• Every request must include a custom User-Agent header such as YourCompany/Location or MyOrg/CloudOps.
• Requests without a valid User-Agent return a 400 JSON error response.
• The /health endpoint includes additional diagnostics for cache and KV status.

🔧 Architecture

Caching Strategy

1. Memory Cache (Tier 1): Instant access for frequently requested data
2. KV Storage (Tier 2): Persistent storage with automatic memory promotion
3. 12-Hour TTL: Optimal balance between freshness and performance

Monitoring

• Cache hit/miss tracking via X-Cache-Status headers
• Performance metrics and response time monitoring
• Automated health checks and diagnostics

Request intelligence dashboard

The dashboard groups reports into Traffic, Audience, and Potential abuse views. Horizontal tabs show one report at a time and retain each view's selected report when switching views. On narrow screens, the report tabs scroll horizontally.

Use Left/Right Arrow, Home, and End to navigate tabs. Filtering, the low-volume row toggle, sorting, and CSV export remain available for table reports; the daily traffic chart is independent of filtering.

The User agents and Client families tables combine user agents matching sc<hex>/Sweden (one or more hexadecimal digits) into a single sc*/Sweden entry. Request counts are summed, and the Client families Variants column retains the number of distinct original user agents. Other client families still group by the name before the first /. Detailed high-volume request windows retain their original user agents.

📊 API Endpoints

Endpoint	Description	Cache TTL
/apps	List all supported applications	12 hours
/app/{appId}	Get specific application details	12 hours
/endpoints/versions	Version check endpoints	12 hours
/endpoints/downloads	Download endpoints	12 hours
/health	System health and diagnostics	No cache

🧪 Testing

Automated Testing

• Pull Request Validation: Automatic testing on PR creation
• Multi-Environment: Tests against both production and development APIs
• Performance Testing: Cache behavior and response time validation
• Security Scanning: Dependency audits and vulnerability checks

Manual Testing

# Run test suite
cd tests
npm install
npm test

# Test caching behavior
./test-caching-simple.sh

🔒 Security

• Regular dependency audits
• API security validation
• Input sanitization and validation
• Rate limiting awareness
• License compliance checking

📈 Performance

Cache Performance

• Memory Cache Hit: ~1ms response time
• KV Cache Miss: ~50-100ms response time
• Cache Efficiency: 90%+ hit rate for popular endpoints
• KV Read Reduction: 95% reduction in KV operations

Monitoring

# Check cache status
curl -H "User-Agent: YourApp/1.0.0" https://evergreen-api.stealthpuppy.com/health

# Monitor cache headers
curl -I -H "User-Agent: YourApp/1.0.0" https://evergreen-api.stealthpuppy.com/apps

🛠️ Development

Local Development

# Install dependencies
npm install

# Start development server
wrangler dev

# Run tests
cd tests && npm test

Deployment

Run these commands from the src directory, where wrangler.toml lives.

# Deploy to staging (https://evergreen-api-staging.stealthpuppy.workers.dev)
npm run deploy:staging

# Deploy to production
npm run deploy:production

Validating changes in staging

The staging environment deploys to the evergreen-api-staging worker. It reads from the same EVERGREEN KV namespace as production, so it serves the same data. Request logs and analytics go to a separate R2 bucket (evergreen-api-staging) and Analytics Engine dataset (evergreen_requests_staging).

# Deploy and tail staging logs
cd src
npm run deploy:staging
npm run tail:staging

# Run the API tests against staging
cd ../tests
API_TEST_USERAGENT="<user agent>" npm run test:staging

Pushing to the staging branch also deploys to staging and runs the API tests through the Deploy to Staging workflow. Once staging passes, merge to main and deploy to production.

📚 Documentation

• API Documentation
• OpenAPI Schema
• Workflow Documentation
• Caching Implementation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit pull request
5. Automated workflows will validate your changes

Guidelines

• Include tests for new features
• Maintain API compatibility
• Update documentation as needed
• Follow security best practices

📋 Requirements

• Node.js 18+ for development
• Cloudflare Workers account
• KV namespace: EVERGREEN
• R2 bucket: evergreen-api (for logging)

🔧 Configuration

Environment Variables

• ENVIRONMENT: deployment environment (production/staging/dev), reported by /health

Bindings

• EVERGREEN: KV namespace for application data
• LOGS_BUCKET: R2 bucket for request logging

🚨 Monitoring & Alerts

• GitHub Actions for CI/CD pipeline
• Automated security scanning
• Performance regression detection
• Dependency update notifications