API.md

# API Documentation

## Overview

The Rust Web Server provides a RESTful API with endpoints for server information, health checks, statistics, and more.

## Base URL

```
http://localhost:8080
```

## Authentication

Some endpoints may require authentication. When authentication is enabled, include the JWT token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```

## Endpoints

### Health Check

Get the current health status of the server.

**Endpoint:** `GET /health`

**Response:**
```json
{
"status": "healthy",
"timestamp": "2026-01-23T10:00:00Z",
"uptime_seconds": 3600,
"active_connections": 5
}
```

### Server Information

Get detailed information about the server.

**Endpoint:** `GET /api/info`

**Response:**
```json
{
"name": "Rust Web Server",
"version": "0.1.0",
"description": "High-performance web server built with Rust",
"author": "RSK World",
"contact": {
"website": "https://rskworld.in",
"email": "hello@rskworld.in",
"phone": "+91 93305 39277",
"address": "Nutanhat, Mongolkote, Purba Burdwan, West Bengal, India, 713147"
},
"features": [
"High performance",
"Async request handling",
"Memory safety",
"Concurrent connections",
"Static file serving",
"Systems programming"
],
"technologies": [
"Rust",
"Tokio",
"Async/Await",
"HTTP Server",
"Memory Safety",
"Concurrency"
]
}
```

### Server Statistics

Get server performance statistics and metrics.

**Endpoint:** `GET /api/stats`

**Response:**
```json
{
"uptime_seconds": 3600,
"request_count": 1250,
"active_connections": 5,
"memory_usage_mb": 42.0,
"cpu_usage_percent": 15.2,
"total_requests": 1250,
"avg_response_time_ms": 12.5
}
```

### Echo Service

Echo back the request data with additional metadata.

**Endpoint:** `POST /api/echo`

**Request Body:**
```json
{
"message": "Hello, World!",
"user": "test-user"
}
```

**Response:**
```json
{
"message": "Hello, World!",
"user": "test-user",
"timestamp": "2026-01-23T10:00:00Z",
"method": "POST",
"path": "/api/echo",
"headers": {
"content-type": "application/json",
"user-agent": "curl/7.68.0"
}
}
```

### File Upload

Upload files to the server.

**Endpoint:** `POST /api/upload`

**Content-Type:** `multipart/form-data`

**Parameters:**
- `file`: The file to upload

**Response:**
```json
{
"filename": "uploaded_file.txt",
"original_filename": "document.txt",
"size": 1024,
"content_type": "text/plain",
"upload_time": "2026-01-23T10:00:00Z",
"url": "/uploads/uploaded_file.txt"
}
```

### Authentication Endpoints

#### Login

**Endpoint:** `POST /api/auth/login`

**Request Body:**
```json
{
"username": "admin",
"password": "password"
}
```

**Response:**
```json
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"user": {
"id": "user-123",
"username": "admin",
"email": "admin@example.com",
"role": "Admin"
},
"expires_at": "2026-01-23T11:00:00Z"
}
```

#### Register

**Endpoint:** `POST /api/auth/register`

**Request Body:**
```json
{
"username": "newuser",
"email": "user@example.com",
"password": "securepassword"
}
```

**Response:**
```json
{
"message": "User registered successfully",
"user_id": "user-456"
}
```

## Error Responses

All API endpoints return appropriate HTTP status codes and error messages:

### 400 Bad Request
```json
{
"error": "Bad Request",
"message": "Invalid request parameters",
"details": "The 'username' field is required"
}
```

### 401 Unauthorized
```json
{
"error": "Unauthorized",
"message": "Authentication required"
}
```

### 403 Forbidden
```json
{
"error": "Forbidden",
"message": "Access denied"
}
```

### 404 Not Found
```json
{
"error": "Not Found",
"message": "Endpoint not found"
}
```

### 500 Internal Server Error
```json
{
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
```

## Rate Limiting

The API implements rate limiting to prevent abuse:

- **General endpoints:** 100 requests per minute per IP
- **Authentication endpoints:** 10 requests per minute per IP
- **File upload:** 5 uploads per minute per user

Rate limit headers are included in responses:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642934460
```

## CORS

Cross-Origin Resource Sharing is supported. By default, the server allows requests from:
- `http://localhost:3000`
- `http://localhost:8080`

## Content Types

The API supports the following content types:
- `application/json`
- `multipart/form-data` (for file uploads)
- `text/plain`

## Versioning

The API uses URL-based versioning. The current version is v1 (no version prefix in URLs).

---

**© 2026 RSK World. All rights reserved.**