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

🔧 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

📊 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

# Deploy to staging
wrangler deploy --env staging

# Deploy to production
wrangler deploy --env 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)

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