Skip to content

Commit 317527f

Browse files
RandithaKRandithaK
committed
docs: update README.md with detailed overview, technology stack, route configuration, and environment variables
1 parent 311b536 commit 317527f

1 file changed

Lines changed: 192 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 192 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,106 @@
1-
# API Gateway
1+
# 🚪 API Gateway
22

3-
This is a lightweight API Gateway implemented in Go using `chi` and `httputil.ReverseProxy`.
4-
It reads service mappings from `config.yaml` and supports JWT authentication, header injection, CORS, and environment variable-based overrides.
3+
> Central entry point for all API requests in the CS02 E-Commerce Platform
54
6-
Quickstart:
5+
## 📋 Overview
76

8-
1. Build and run locally:
7+
This is a lightweight API Gateway implemented in Go using `chi` router and `httputil.ReverseProxy`. It serves as the single entry point for all frontend requests, handling JWT authentication, request routing, CORS, and header injection.
8+
9+
## 🛠️ Technology Stack
10+
11+
| Component | Technology | Version |
12+
|-----------|------------|---------|
13+
| Language | Go | 1.20+ |
14+
| Router | Chi (go-chi/chi) | v5 |
15+
| JWT | golang-jwt | v4 |
16+
| CORS | go-chi/cors | Latest |
17+
| Config | gopkg.in/yaml.v3 | Latest |
18+
19+
## 🚀 Route Configuration
20+
21+
| Path Prefix | Target Service | Port | Auth Required |
22+
|-------------|----------------|------|---------------|
23+
| `/api/auth/*` | user-identity-service | 8081 | No |
24+
| `/api/users/*` | user-identity-service | 8081 | Yes |
25+
| `/api/products/*` | product-catalogue-service | 8082 | No |
26+
| `/api/builder/*` | product-catalogue-service | 8082 | No |
27+
| `/api/cart/*` | shoppingcart-wishlist-service | 8084 | Yes |
28+
| `/api/wishlist/*` | shoppingcart-wishlist-service | 8084 | Yes |
29+
| `/api/orders/*` | order-service | 8083 | Yes |
30+
| `/api/trade-in/*` | order-service | 8083 | Yes |
31+
| `/api/notifications/*` | notifications-service | 8087 | Yes |
32+
| `/api/content/*` | content-service | 8086 | No |
33+
| `/api/support/*` | support-service | 8085 | Yes |
34+
| `/api/warranty/*` | support-service | 8085 | Yes |
35+
| `/api/analytics/*` | reporting-and-analysis-service | 8088 | Yes |
36+
| `/api/ai/*` | AI-service | 8089 | No |
37+
| `/healthz` | Gateway health check | - | No |
38+
39+
## 🔧 Configuration
40+
41+
### Environment Variables
42+
43+
| Variable | Required | Default | Description |
44+
|----------|----------|---------|-------------|
45+
| `JWT_SECRET` | Yes | - | Secret key for JWT validation |
46+
| `FRONTEND_ORIGINS` | No | `http://localhost:3000` | Allowed CORS origins |
47+
| `USER_IDENTITY_SERVICE_URL` | No | `http://localhost:8081` | User service URL |
48+
| `PRODUCT_CATALOGUE_SERVICE_URL` | No | `http://localhost:8082` | Product service URL |
49+
| `ORDER_SERVICE_URL` | No | `http://localhost:8083` | Order service URL |
50+
| `CART_SERVICE_URL` | No | `http://localhost:8084` | Cart service URL |
51+
| `SUPPORT_SERVICE_URL` | No | `http://localhost:8085` | Support service URL |
52+
| `CONTENT_SERVICE_URL` | No | `http://localhost:8086` | Content service URL |
53+
| `NOTIFICATIONS_SERVICE_URL` | No | `http://localhost:8087` | Notifications service URL |
54+
| `ANALYTICS_SERVICE_URL` | No | `http://localhost:8088` | Analytics service URL |
55+
| `AI_SERVICE_URL` | No | `http://localhost:8089` | AI service URL |
56+
57+
### config.yaml
58+
59+
```yaml
60+
server:
61+
port: 8080
62+
63+
services:
64+
user-identity-service:
65+
url: http://localhost:8081
66+
product-catalogue-service:
67+
url: http://localhost:8082
68+
# ... additional services
69+
70+
jwt:
71+
secret: ${JWT_SECRET}
72+
73+
cors:
74+
allowed_origins:
75+
- http://localhost:3000
76+
```
77+
78+
## 📦 Dependencies
79+
80+
```go
81+
require (
82+
github.com/go-chi/chi/v5 v5.0.10
83+
github.com/go-chi/cors v1.2.1
84+
github.com/golang-jwt/jwt/v4 v4.5.0
85+
gopkg.in/yaml.v3 v3.0.1
86+
)
87+
```
88+
89+
## 🏃 Running the Service
90+
91+
### Local Development
992

1093
```bash
1194
cd backend/api-gateway
95+
1296
# Build
1397
GO111MODULE=on go build -o apigateway .
98+
1499
# Run
15100
./apigateway
16101
```
17102

18-
2. Override service URLs and JWT secret with environment variables when needed:
103+
### With Environment Variables
19104

20105
```bash
21106
export JWT_SECRET="mysecret"
@@ -24,20 +109,115 @@ export FRONTEND_ORIGINS="http://localhost:3000"
24109
./apigateway
25110
```
26111

27-
3. Use Docker:
112+
### Docker
28113

29114
```bash
30115
cd backend/api-gateway
116+
117+
# Build image
31118
docker build -t cs02/apigateway:latest .
32-
docker run -p 8080:8080 -e JWT_SECRET=mysecret cs02/apigateway:latest
119+
120+
# Run container
121+
docker run -p 8080:8080 \
122+
-e JWT_SECRET=mysecret \
123+
-e USER_IDENTITY_SERVICE_URL=http://user-identity-service:8081 \
124+
cs02/apigateway:latest
33125
```
34126

35-
4. Run unit tests:
127+
### Using Makefile
36128

37129
```bash
130+
make build # Build the binary
131+
make run # Run the gateway
132+
make test # Run tests
133+
make docker # Build Docker image
134+
```
135+
136+
## 🔐 Authentication Flow
137+
138+
1. **Public Routes**: Requests to `/api/auth/*`, `/api/products/*`, `/api/content/*`, `/api/ai/*` pass through without auth
139+
2. **Protected Routes**: All other routes require a valid JWT token
140+
3. **Token Extraction**: JWT is extracted from `Authorization: Bearer <token>` header
141+
4. **Validation**: Token signature verified using HS256 algorithm
142+
5. **Header Injection**: On successful auth, gateway injects:
143+
- `X-User-Subject`: User's subject claim
144+
- `X-User-Id`: User's ID claim
145+
- `X-User-Roles`: User's roles claim
146+
147+
## ✅ Features - Completion Status
148+
149+
| Feature | Status | Notes |
150+
|---------|--------|-------|
151+
| Reverse proxy routing | ✅ Complete | All services routed |
152+
| JWT authentication middleware | ✅ Complete | HS256 tokens |
153+
| User info header injection | ✅ Complete | X-User-Id, X-User-Subject, X-User-Roles |
154+
| CORS handling | ✅ Complete | Configurable origins |
155+
| Health check endpoint | ✅ Complete | `/healthz` |
156+
| Environment variable config | ✅ Complete | Override via env vars |
157+
| YAML configuration | ✅ Complete | `config.yaml` |
158+
| Graceful shutdown | ✅ Complete | Handles SIGTERM |
159+
| Request logging | ✅ Complete | Chi middleware |
160+
161+
### **Overall Completion: 100%** ✅
162+
163+
## ❌ Not Implemented / Future Enhancements
164+
165+
| Feature | Priority | Notes |
166+
|---------|----------|-------|
167+
| Rate limiting | Medium | Recommended for production |
168+
| Request caching | Low | Could cache product requests |
169+
| Circuit breaker | Medium | For service resilience |
170+
| API versioning | Low | Currently v1 only |
171+
| RS256 JWT support | Low | Currently HS256 only |
172+
| Metrics/Prometheus | Medium | For monitoring |
173+
| Distributed tracing | Low | OpenTelemetry integration |
174+
175+
## 📁 Project Structure
176+
177+
```
178+
api-gateway/
179+
├── main.go # Application entry point
180+
├── main_test.go # Unit tests
181+
├── config.yaml # Service configuration
182+
├── go.mod # Go module definition
183+
├── Dockerfile # Container configuration
184+
├── Makefile # Build commands
185+
├── run.sh # Development script
186+
└── README.md # This file
187+
```
188+
189+
## 🧪 Testing
190+
191+
```bash
192+
# Run unit tests
38193
go test ./...
194+
195+
# Run with verbose output
196+
go test -v ./...
197+
198+
# Test health endpoint
199+
curl http://localhost:8080/healthz
200+
201+
# Test with JWT token
202+
curl -H "Authorization: Bearer <token>" http://localhost:8080/api/users/me
39203
```
40204

41-
Notes:
42-
- By default the gateway listens on :8080, adjust `config.yaml:server.port` as necessary.
43-
- This gateway uses HS256 tokens for JWT parsing; if you use RSA tokens (RS256), the parsing logic must be updated.
205+
## 🔗 Related Services
206+
207+
All backend microservices are routed through this gateway:
208+
- [User Identity Service](../user-identity-service/README.md)
209+
- [Product Catalogue Service](../product-catalogue-service/README.md)
210+
- [Order Service](../order-service/README.md)
211+
- [Shopping Cart Service](../shoppingcart-wishlist-service/README.md)
212+
- [Support Service](../support-service/README.md)
213+
- [Content Service](../content-service/README.md)
214+
- [Notifications Service](../notifications-service/README.md)
215+
- [Reporting Service](../reporting-and-analysis-service/README.md)
216+
- [AI Service](../AI-service/README.md)
217+
218+
## 📝 Notes
219+
220+
- Default port is **8080**, configurable via `config.yaml`
221+
- Uses **HS256** tokens; update parsing logic for RS256
222+
- All service URLs can be overridden via environment variables
223+
- CORS is configured to allow frontend origins

0 commit comments

Comments
 (0)