YARP Microservices Gateway Example Project

Overview

This is a complete microservices gateway example project based on YARP (Yet Another Reverse Proxy), demonstrating core concepts of modern microservices architecture including API gateway, reverse proxy, load balancing, canary deployment, and more.

🎯 Project Goals

• Demonstrate practical application of YARP in .NET 8.0
• Showcase key features of microservices gateway: routing, security, monitoring, traffic management
• Provide runnable complete examples for learning and testing
• Support bilingual documentation (English and Chinese) suitable for international teams

🏗️ Project Architecture

YarpExample/
├── ApiGateway/           # YARP-based API Gateway (core component)
├── StudentApi/          # Student Information Management API Service
├── CourseApi/           # Course Information Management API Service
├── Bruno/               # API Test Collection (using Bruno testing tool)
└── services-*.bat       # Service management scripts

Architecture Diagram

Client Request
    ↓
┌─────────────────────────────────────────┐
│           API Gateway (Port 7000)       │
│   - JWT Authentication & Authorization  │
│   - Routing & Load Balancing            │
│   - Rate Limiting & Caching             │
│   - Distributed Tracing                 │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ↓             ↓             ↓
┌─────────┐ ┌─────────┐ ┌─────────┐
│Student  │ │Student  │ │Course   │
│Stable   │ │Canary   │ │API      │
│(7003)   │ │(7004)   │ │(7001/2) │
└─────────┘ └─────────┘ └─────────┘

🚀 Quick Start

1. Prerequisites

• .NET 8.0 SDK or higher
• Windows/Linux/macOS operating system
• Recommended: Visual Studio Code or Visual Studio 2022

2. Start All Services with One Click

# Windows
services-start-all.bat

# Or start manually (recommended for development):
# Gateway: cd ApiGateway && dotnet run --launch-profile http
# Course API Instance 1: cd CourseApi && dotnet run --launch-profile http-port-7001
# Course API Instance 2: cd CourseApi && dotnet run --launch-profile http-port-7002
# Student API Stable: cd StudentApi && dotnet run --launch-profile http-7003-stable-version
# Student API Canary: cd StudentApi && dotnet run --launch-profile http-7004-canary-version

3. Verify Services are Running

# Check gateway health status
curl http://localhost:7000/gateway/api/students/healthcheck

# Test Student API
curl http://localhost:7000/gateway/api/students

# Test Course API
curl http://localhost:7000/gateway/api/courses

# Test canary version
curl -H "X-Canary: true" http://localhost:7000/gateway/api/students

📦 Sub-project Introduction

1. ApiGateway - Core Gateway

Built with YARP, provides the following features:

• Dynamic Routing Configuration: Load routing rules from appsettings.json
• JWT Authentication: Support for Bearer token validation
• Load Balancing: Weighted load balancing (80%/20%) and RoundRobin load balancing
• Rate Limiting: Fixed window rate limiting (4 requests per 12 seconds)
• Output Caching: Header-based response caching
• Health Monitoring: Active monitoring of backend service health
• Distributed Tracing: OpenTelemetry integration
• Canary Deployment: Support for routing to canary version via headers

2. StudentApi - Student API Service

RESTful API service with features:

• Dual Version Deployment: Stable version (port 7003) and Canary version (port 7004)
• Gateway Protection: Uses X-Internal-Gateway-Token to prevent direct access
• Version Awareness: Responses include service version and port information
• Health Checks: Independent health check endpoints for load balancing

3. CourseApi - Course API Service

RESTful API service with features:

• Multi-instance Deployment: Two instances (ports 7001 and 7002) with RoundRobin load balancing
• Dynamic Versioning: Version switching based on x-api-version header
• Comprehensive Management: Course creation, querying, enrollment, drop functionality
• Business Validation: Business rule validation for price, credits, capacity, etc.

🔧 Key Configuration

1. Routing Configuration

{
  "student-canary-route": {
    "ClusterId": "student-canary-cluster",
    "Order": 1,  // Higher priority
    "Headers": [{ "Name": "X-Canary", "Values": ["true"] }]
  },
  "student-stable-route": {
    "ClusterId": "student-stable-cluster", 
    "Order": 2,  // Lower priority (default route)
  },
  "courseRoute": {
    "ClusterId": "course-cluster",
    "LoadBalancingPolicy": "RoundRobin"
  }
}

2. Load Balancing Strategies

• Student API: Weighted load balancing (80% stable, 20% canary)
• Course API: RoundRobin load balancing (equal distribution between two instances)

3. Security Configuration

• JWT Tokens: For client authentication
• Internal Gateway Token: X-Internal-Gateway-Token prevents direct backend calls
• Rate Limiting: Protects gateway and backend services

🧪 Testing & Debugging

1. API Testing with Bruno

The project includes complete Bruno test collections:

# Import the test collections from Bruno/ directory in Bruno

2. Debug Endpoints

# View request headers (for debugging)
GET http://localhost:7000/gateway/api/students/debug/headers

# Health check endpoints
GET http://localhost:7003/api/students/healthcheck
GET http://localhost:7001/api/courses/healthcheck

3. Monitoring Metrics

• OpenTelemetry Tracing: View distributed traces through Jaeger or Zipkin
• Service Port Information: Responses include the port of the service that processed the request
• Version Information: Responses include service version identifiers

📊 Traffic Management Examples

1. Canary Deployment Testing

# Default route to stable version (80% traffic)
curl http://localhost:7000/gateway/api/students

# Explicit route to canary version (20% traffic)
curl -H "X-Canary: true" http://localhost:7000/gateway/api/students

2. API Version Control

# Old version API
curl http://localhost:7000/gateway/api/courses

# New version API (v2)
curl -H "x-api-version: v2" http://localhost:7000/gateway/api/courses

3. Load Balancing Verification

# Make multiple requests to Course API, observe different port responses
for i in {1..5}; do
  curl -s http://localhost:7000/gateway/api/courses | grep "port"
done

🛡️ Security Features

1. Prevention of Direct Backend Calls

• All backend services validate X-Internal-Gateway-Token
• Token value: 9801919d-b188-42ab-bb2d-7243aba370aa
• Only requests coming through the gateway are accepted

2. JWT Authentication

# Request with JWT token
curl -H "Authorization: Bearer {jwt-token}" \
     -H "X-Internal-Gateway-Token: 9801919d-b188-42ab-bb2d-7243aba370aa" \
     http://localhost:7000/gateway/api/students

3. Rate Limiting Protection

• Maximum 4 requests per 12 seconds
• Exceeding limits returns HTTP 503
• Prevents DDoS attacks and resource exhaustion

📚 Learning Resources

1. Documentation Structure

├── ApiGateway/README.md      # Gateway English documentation
├── ApiGateway/README_CN.md   # Gateway Chinese documentation
├── StudentApi/Readme.md      # Student API English documentation  
├── StudentApi/Readme_CN.md   # Student API Chinese documentation
├── CourseApi/Readme.md       # Course API English documentation
├── CourseApi/Readme_CN.md    # Course API Chinese documentation
├── README.md                 # Main project Chinese documentation
└── README_EN.md              # Main project English documentation

2. Key Concepts

• YARP (Yet Another Reverse Proxy): Microsoft's official reverse proxy library
• Canary Deployment: Gradually rolling out new versions to reduce risk
• Load Balancing: Distributing traffic across different service instances
• Session Affinity: Routing the same user's requests to the same backend
• Distributed Tracing: End-to-end tracing of cross-service requests

3. Related Technologies

• .NET 8.0: Cross-platform development framework
• OpenTelemetry: Observability standard
• JWT (JSON Web Tokens): Authentication standard
• Bruno: API testing tool

🚨 Troubleshooting

Common Issues

1. Service Startup Failure

   # Check port usage
   netstat -ano | findstr :7000
   
   # Check .NET SDK version
   dotnet --version

2. Gateway Routing Errors

   • Confirm all backend services are started
   • Check routing configuration in appsettings.json
   • Verify health check endpoints are accessible

3. Authentication Failures

   • Confirm JWT token is valid
   • Check if X-Internal-Gateway-Token is correct
   • View detailed error messages in gateway logs

Viewing Logs

# Gateway logs (debug level)
# Check Logging configuration in ApiGateway/appsettings.json

🔮 Future Enhancements

Planned Features

1. Swagger/OpenAPI Integration: Automatic API documentation generation
2. Prometheus Metrics: Monitoring metrics export
3. Configuration Management: Dynamic configuration updates
4. Multi-tenancy Support: Tenant-isolated routing and policies
5. WebSocket Support: Real-time communication

Extension Directions

1. Add New Services: Add more microservices following existing patterns
2. Identity Provider: Integrate Keycloak or Auth0
3. Message Queue: Integrate RabbitMQ or Kafka
4. Database Integration: Replace in-memory storage with real database

🤝 Contribution Guidelines

Code Standards

• Follow .NET coding conventions
• Add XML documentation comments to all public APIs
• Add bilingual comments to important configurations

Documentation Requirements

• All new features require updating relevant README files
• Keep English and Chinese documentation synchronized
• Code examples should be complete and runnable

Testing Requirements

• New features require corresponding Bruno tests
• Important changes require updating service startup scripts

📄 License

This project is licensed under the MIT License. See the LICENSE file in the project root for details.

🙏 Acknowledgments

• YARP Team: For providing an excellent reverse proxy library
• .NET Community: For rich ecosystem and tools
• OpenTelemetry Project: For standardizing observability

---

Important Note: This project is primarily for demonstration and learning purposes. For production use, please perform security hardening and performance optimization based on actual requirements.

📞 Support & Feedback

For issues or suggestions, please submit feedback through the project's Issue page.