REST APIs: How Applications Talk to Each Other

REST APIs: How Applications Talk to Each Other

1. Understanding REST Architecture

REST (Representational State Transfer) is a standard way for applications to communicate over HTTP.

REST Principles:
1. Client-Server - Separate concerns
2. Statelessness - Each request is independent
3. Resource-Based - URLs represent resources (nouns, not verbs)
4. HTTP Methods - Use standard HTTP verbs for operations

Resources in an E-Commerce API:
/products - Collection of products
/products/123 - Specific product with ID 123
/users/456/orders - Orders belonging to user 456
/categories/electronics/products - Products in electronics category

Key Concept: URLs should be NOUNS (things), not VERBS (actions)

BAD (not REST):
/getProducts
/createProduct
/updateProduct
/deleteProduct

GOOD (REST):
GET /products
POST /products
PUT /products/123
DELETE /products/123 

2. HTTP Methods - CRUD Operations

REST uses HTTP methods to perform operations on resources.

// GET - Retrieve data (Safe, Idempotent)
fetch('/api/products') .then(res => res.json()) .then(data => console.log("सभी प्रोडक्ट:", data));

fetch('/api/products/123') .then(res => res.json()) .then(data => console.log("प्रोडक्ट विवरण:", data));

// POST - Create new resource (Not idempotent)
fetch('/api/products', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'iPhone 15', price: 79999, category: 'electronics' })
})
.then(res => res.json())
.then(data => console.log("नया प्रोडक्ट बनाया गया:", data));

// PUT - Update entire resource (Idempotent)
fetch('/api/products/123', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'iPhone 15 Pro', price: 99999, category: 'electronics' })
})
.then(res => res.json())
.then(data => console.log("प्रोडक्ट अपडेट:", data));

// PATCH - Update partial resource (Idempotent)
fetch('/api/products/123', { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ price: 89999 // Only update price })
})
.then(res => res.json())
.then(data => console.log("प्रोडक्ट अपडेट:", data));

// DELETE - Remove resource (Idempotent)
fetch('/api/products/123', { method: 'DELETE'
})
.then(res => res.json())
.then(data => console.log("प्रोडक्ट डिलीट:", data));

// HTTP Method Properties:
// Idempotent = Multiple calls = Same result
// GET, PUT, DELETE = Idempotent
// POST, PATCH = Not idempotent 

3. HTTP Status Codes

API responses use standard HTTP status codes to indicate success or failure.

// 2xx Success
200 OK - Request succeeded
201 Created - Resource created successfully
202 Accepted - Request accepted, processing
204 No Content - Successful, no response body

// 3xx Redirection
301 Moved Permanently - Resource moved to new URL
302 Found - Temporary redirect
304 Not Modified - Use cached version

// 4xx Client Error
400 Bad Request - Invalid request syntax
401 Unauthorized - Authentication required
403 Forbidden - Authenticated but no permission
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded

// 5xx Server Error
500 Internal Server Error - Server error
502 Bad Gateway - Invalid response from upstream
503 Service Unavailable - Server temporarily down

// Handling different status codes
fetch('/api/products/999') .then(res => { if (!res.ok) { // Check if status is 200-299 throw new Error(`HTTP Error: ${res.status}`); } return res.json(); }) .then(data => console.log(data)) .catch(error => { if (error.message.includes('404')) { console.log("प्रोडक्ट नहीं मिला"); } else if (error.message.includes('500')) { console.log("सर्वर त्रुटि"); } else { console.log("नेटवर्क त्रुटि"); } }); 

4. Request and Response Headers

Headers provide metadata about the request and response.

// Common Request Headers
const headers = { 'Content-Type': 'application/json', // What format we're sending 'Accept': 'application/json', // What format we want back 'Authorization': 'Bearer TOKEN123', // Authentication token 'User-Agent': 'MyApp/1.0', // Client identification 'Cache-Control': 'no-cache' // Don't use cached version
};

fetch('/api/products', { method: 'POST', headers: headers, body: JSON.stringify({ name: 'नया प्रोडक्ट' })
});

// Common Response Headers
// Content-Type: application/json
// Cache-Control: max-age=3600
// X-RateLimit-Limit: 1000
// X-RateLimit-Remaining: 999
// X-RateLimit-Reset: 1640000000

// Accessing response headers
fetch('/api/products') .then(res => { console.log('Content-Type:', res.headers.get('content-type')); console.log('Rate Limit:', res.headers.get('x-ratelimit-remaining')); return res.json(); });

// Custom headers for API
const authToken = localStorage.getItem('authToken');
fetch('/api/user/profile', { headers: { 'Authorization': `Bearer ${authToken}`, 'X-API-Key': 'YOUR_API_KEY' }
}); 

5. URL Structure and Query Parameters

URLs can include query parameters for filtering, sorting, and pagination.

// Basic URL
/api/products

// Query Parameters (filter and search)
/api/products?category=electronics&price_max=50000

// Sorting
/api/products?sort=price&order=asc

// Pagination
/api/products?page=2&limit=20

// Complex query
/api/products?category=electronics&price_min=10000&price_max=50000&sort=rating&order=desc&page=1&limit=10

// Building URLs programmatically
const baseURL = 'https://api.example.com/products';
const params = new URLSearchParams({ category: 'electronics', minPrice: 10000, maxPrice: 50000, sortBy: 'rating', order: 'desc', page: 1, limit: 20
});

const fullURL = `${baseURL}?${params.toString()}`;
fetch(fullURL).then(r => r.json()).then(data => console.log(data));

// Better approach with URL object
const url = new URL('https://api.example.com/products');
url.searchParams.append('category', 'electronics');
url.searchParams.append('minPrice', 10000);
url.searchParams.append('maxPrice', 50000);

fetch(url.toString()).then(r => r.json()); 

6. Understanding UPI API Flow (India Context)

Real-world example: How UPI (Unified Payments Interface) works conceptually.

// UPI Transaction Flow (Conceptual)
// Used by apps like Google Pay, PhonePe, Paytm

// Step 1: Initiate Payment
const paymentRequest = { upiId: 'user@okhdfcbank', amount: 5000, transactionRef: 'TXN123456', merchant: 'example.com', description: 'Order #12345'
};

// Step 2: Send request to UPI Provider API
fetch('https://api.upi-provider.com/initiate', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer API_KEY' }, body: JSON.stringify(paymentRequest)
})
.then(res => res.json())
.then(data => { // Step 3: Get transaction ID const txnId = data.transactionId; console.log('लेनदेन शुरू किया गया:', txnId); // Step 4: Redirect to UPI app or payment page window.location.href = data.paymentUrl;
});

// Step 5: Callback (Payment app confirms transaction)
// Server receives confirmation
const confirmPayment = (txnId, status) => { return fetch('https://api.example.com/confirm-payment', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ transactionId: txnId, status: status, // 'SUCCESS' or 'FAILED' timestamp: new Date().toISOString() }) });
};

// Step 6: Check transaction status
const checkPaymentStatus = (txnId) => { return fetch(`https://api.example.com/payment/${txnId}`) .then(res => res.json()) .then(data => { if (data.status === 'SUCCESS') { console.log('भुगतान सफल!'); } else if (data.status === 'PENDING') { console.log('भुगतान लंबित है'); } else { console.log('भुगतान विफल'); } return data; });
};

// Real UPI APIs used in India:
// NPCI (National Payments Corporation of India) - BHIM API
// RazorPay UPI
// PayU
// Google Pay API
// PhonePe Payment Gateway 

7. Building a Complete API Client

class APIClient { constructor(baseURL, apiKey) { this.baseURL = baseURL; this.apiKey = apiKey; } async request(endpoint, options = {}) { const url = `${this.baseURL}${endpoint}`; const headers = { 'Content-Type': 'application/json', 'X-API-Key': this.apiKey, ...options.headers }; try { const response = await fetch(url, { ...options, headers }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } return await response.json(); } catch (error) { console.error('API Error:', error); throw error; } } // CRUD methods async getAll(resource) { return this.request(`/${resource}`); } async getOne(resource, id) { return this.request(`/${resource}/${id}`); } async create(resource, data) { return this.request(`/${resource}`, { method: 'POST', body: JSON.stringify(data) }); } async update(resource, id, data) { return this.request(`/${resource}/${id}`, { method: 'PUT', body: JSON.stringify(data) }); } async delete(resource, id) { return this.request(`/${resource}/${id}`, { method: 'DELETE' }); }
}

// Usage
const api = new APIClient('https://api.flipkart-clone.com', 'my-api-key');

// Get all products
const products = await api.getAll('products');

// Get one product
const product = await api.getOne('products', 123);

// Create new product
const newProduct = await api.create('products', { name: 'iPhone 15', price: 79999
});

// Update product
const updated = await api.update('products', 123, { price: 69999
});

// Delete product
await api.delete('products', 123); 

Key Takeaways

• REST uses HTTP methods to perform CRUD operations
• Use nouns (resources) in URLs, not verbs
• GET/DELETE are safe and idempotent
• POST/PATCH are not idempotent
• HTTP status codes indicate success or failure
• Headers provide metadata about request/response
• Query parameters filter, sort, and paginate data
• Learn from real APIs like UPI, Google Pay, payment gateways
• Wrap API calls in reusable client classes