create-aziz-app 2.0.11 → 2.0.13

package/template/docs/API-ROUTES.md

@@ -0,0 +1,538 @@
+# API Routes Guide
+
+## Overview
+
+API routes run on the **SERVER** (Node.js), just like Next.js! They're real backend endpoints, not client-side mocks.
+
+## How It Works
+
+```
+Browser                    Dev Server (Node.js)
+   │                              │
+   │  GET /api/users              │
+   ├─────────────────────────────►│
+   │                              │ Loads api/users.js
+   │                              │ Executes handler()
+   │                              │
+   │  { users: [...] }            │
+   │◄─────────────────────────────┤
+   │                              │
+```
+
+## Creating an API Route
+
+### File Structure
+
+```
+api/
+├── hello.js       → /api/hello
+├── users.js       → /api/users
+└── posts.js       → /api/posts
+```
+
+Each file in `api/` becomes an endpoint!
+
+### Basic Example
+
+```javascript
+// api/hello.js
+
+module.exports = async function handler(req, res) {
+    return res.status(200).json({
+        message: 'Hello from the server!'
+    });
+};
+```
+
+### Request Object
+
+The `req` object contains:
+
+```javascript
+{
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    body: {},           // Parsed JSON body
+    query: {},          // URL query parameters
+    headers: {},        // Request headers
+    url: '/api/users?id=1'
+}
+```
+
+### Response Object
+
+The `res` object has these methods:
+
+```javascript
+// Set status code
+res.status(200)
+
+// Send JSON response
+res.json({ data: 'value' })
+
+// Send text response
+res.send('Hello')
+
+// Set custom header
+res.setHeader('X-Custom', 'value')
+
+// Chain methods
+res.status(201).json({ created: true })
+```
+
+## Examples
+
+### GET Request
+
+```javascript
+// api/users.js
+
+const users = [
+    { id: 1, name: 'Aziz' },
+    { id: 2, name: 'John' }
+];
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        // Get specific user
+        if (req.query.id) {
+            const user = users.find(u => u.id === parseInt(req.query.id));
+            if (user) {
+                return res.status(200).json(user);
+            }
+            return res.status(404).json({ error: 'User not found' });
+        }
+        
+        // Get all users
+        return res.status(200).json(users);
+    }
+    
+    return res.status(405).json({ error: 'Method not allowed' });
+};
+```
+
+**Usage:**
+```javascript
+// Get all users
+const response = await fetchApi('/api/users');
+const users = await response.json();
+
+// Get specific user
+const response = await fetchApi('/api/users?id=1');
+const user = await response.json();
+```
+
+### POST Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        
+        // Validate
+        if (!name || !email) {
+            return res.status(400).json({ 
+                error: 'Name and email are required' 
+            });
+        }
+        
+        // Create user
+        const newUser = {
+            id: Date.now(),
+            name,
+            email
+        };
+        
+        return res.status(201).json(newUser);
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users', {
+    method: 'POST',
+    body: JSON.stringify({
+        name: 'Aziz',
+        email: 'aziz@example.com'
+    })
+});
+const user = await response.json();
+```
+
+### PUT Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'PUT') {
+        const userId = req.query.id;
+        const updates = req.body;
+        
+        // Update user logic here
+        
+        return res.status(200).json({ 
+            message: 'User updated',
+            user: updatedUser 
+        });
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users?id=1', {
+    method: 'PUT',
+    body: JSON.stringify({
+        name: 'New Name'
+    })
+});
+```
+
+### DELETE Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'DELETE') {
+        const userId = req.query.id;
+        
+        // Delete user logic here
+        
+        return res.status(200).json({ 
+            message: 'User deleted' 
+        });
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users?id=1', {
+    method: 'DELETE'
+});
+```
+
+### Multiple Methods
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    switch (req.method) {
+        case 'GET':
+            // Handle GET
+            return res.status(200).json({ method: 'GET' });
+            
+        case 'POST':
+            // Handle POST
+            return res.status(201).json({ method: 'POST' });
+            
+        case 'PUT':
+            // Handle PUT
+            return res.status(200).json({ method: 'PUT' });
+            
+        case 'DELETE':
+            // Handle DELETE
+            return res.status(200).json({ method: 'DELETE' });
+            
+        default:
+            return res.status(405).json({ 
+                error: 'Method not allowed' 
+            });
+    }
+};
+```
+
+## Using in Components
+
+### Basic Fetch
+
+```jsx
+function MyComponent() {
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(false);
+    
+    const loadData = async () => {
+        setLoading(true);
+        try {
+            const response = await fetchApi('/api/users');
+            const users = await response.json();
+            setData(users);
+        } catch (error) {
+            console.error('Error:', error);
+        }
+        setLoading(false);
+    };
+    
+    return (
+        <div>
+            <button onClick={loadData}>Load Users</button>
+            {loading && <p>Loading...</p>}
+            {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+        </div>
+    );
+}
+```
+
+### With Error Handling
+
+```jsx
+const [error, setError] = useState(null);
+
+const loadData = async () => {
+    try {
+        const response = await fetchApi('/api/users');
+        
+        if (!response.ok) {
+            throw new Error('Failed to fetch');
+        }
+        
+        const users = await response.json();
+        setData(users);
+        setError(null);
+    } catch (err) {
+        setError(err.message);
+        setData(null);
+    }
+};
+```
+
+## Database Integration
+
+### Using a Real Database
+
+```javascript
+// api/users.js
+
+// Example with a database (you need to install the package)
+// npm install better-sqlite3
+
+const Database = require('better-sqlite3');
+const db = new Database('mydb.sqlite');
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        const users = db.prepare('SELECT * FROM users').all();
+        return res.status(200).json(users);
+    }
+    
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        const result = db.prepare(
+            'INSERT INTO users (name, email) VALUES (?, ?)'
+        ).run(name, email);
+        
+        return res.status(201).json({ 
+            id: result.lastInsertRowid,
+            name,
+            email
+        });
+    }
+};
+```
+
+### Using External APIs
+
+```javascript
+// api/weather.js
+
+module.exports = async function handler(req, res) {
+    const city = req.query.city || 'London';
+    
+    try {
+        const response = await fetch(
+            `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=YOUR_KEY`
+        );
+        const data = await response.json();
+        
+        return res.status(200).json(data);
+    } catch (error) {
+        return res.status(500).json({ 
+            error: 'Failed to fetch weather' 
+        });
+    }
+};
+```
+
+## Environment Variables
+
+```javascript
+// api/config.js
+
+module.exports = async function handler(req, res) {
+    // Access environment variables
+    const apiKey = process.env.API_KEY;
+    const dbUrl = process.env.DATABASE_URL;
+    
+    return res.status(200).json({
+        hasApiKey: !!apiKey,
+        hasDbUrl: !!dbUrl
+    });
+};
+```
+
+Set environment variables:
+```bash
+# Windows
+set API_KEY=your_key
+npm run dev
+
+# Mac/Linux
+API_KEY=your_key npm run dev
+```
+
+## Hot Reload
+
+API routes support hot reload! When you save an API file:
+
+1. Dev server detects the change
+2. Reloads the API handler
+3. Next request uses the new code
+4. No server restart needed!
+
+## CORS
+
+CORS is automatically enabled for all API routes:
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+Access-Control-Allow-Headers: Content-Type
+```
+
+## Error Handling
+
+### Server Errors
+
+```javascript
+module.exports = async function handler(req, res) {
+    try {
+        // Your code here
+        const data = await someAsyncOperation();
+        return res.status(200).json(data);
+    } catch (error) {
+        console.error('API Error:', error);
+        return res.status(500).json({ 
+            error: 'Internal server error',
+            message: error.message
+        });
+    }
+};
+```
+
+### Validation Errors
+
+```javascript
+module.exports = async function handler(req, res) {
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        
+        if (!name) {
+            return res.status(400).json({ 
+                error: 'Name is required' 
+            });
+        }
+        
+        if (!email || !email.includes('@')) {
+            return res.status(400).json({ 
+                error: 'Valid email is required' 
+            });
+        }
+        
+        // Process valid data
+    }
+};
+```
+
+## Status Codes
+
+Common HTTP status codes:
+
+- `200` - OK (successful GET, PUT, DELETE)
+- `201` - Created (successful POST)
+- `400` - Bad Request (validation error)
+- `401` - Unauthorized (authentication required)
+- `403` - Forbidden (no permission)
+- `404` - Not Found (resource doesn't exist)
+- `405` - Method Not Allowed (wrong HTTP method)
+- `500` - Internal Server Error (server error)
+
+## Best Practices
+
+### 1. Always Handle Methods
+
+```javascript
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        // Handle GET
+    } else {
+        return res.status(405).json({ 
+            error: 'Method not allowed' 
+        });
+    }
+};
+```
+
+### 2. Validate Input
+
+```javascript
+if (!req.body.name || typeof req.body.name !== 'string') {
+    return res.status(400).json({ error: 'Invalid name' });
+}
+```
+
+### 3. Use Try-Catch
+
+```javascript
+try {
+    const data = await database.query();
+    return res.status(200).json(data);
+} catch (error) {
+    return res.status(500).json({ error: error.message });
+}
+```
+
+### 4. Return Early
+
+```javascript
+if (!user) {
+    return res.status(404).json({ error: 'Not found' });
+}
+
+// Continue with logic
+```
+
+### 5. Use Async/Await
+
+```javascript
+module.exports = async function handler(req, res) {
+    const data = await fetchData();
+    return res.status(200).json(data);
+};
+```
+
+## Comparison with Next.js
+
+| Feature | Aziz App | Next.js |
+|---------|----------|---------|
+| File-based routing | ✅ | ✅ |
+| Server-side execution | ✅ | ✅ |
+| Hot reload | ✅ | ✅ |
+| Request/Response API | ✅ | ✅ |
+| Dynamic routes | ❌ | ✅ |
+| Middleware | ❌ | ✅ |
+| Edge runtime | ❌ | ✅ |
+
+## Summary
+
+- API routes run on the **server** (Node.js)
+- Each file in `api/` becomes an endpoint
+- Use `module.exports` to export the handler
+- Access via `fetchApi('/api/routename')`
+- Supports GET, POST, PUT, DELETE
+- Hot reload enabled
+- CORS enabled by default
+- Just like Next.js API routes!