REST API Design Principles - Database & APIs

1/*
21. CLIENT-SERVER ARCHITECTURE
3   - Separation of concerns between client and server
4   - Server manages data, client manages user interface
5   - Enables independent evolution of both sides
6
72. STATELESSNESS
8   - Each request contains all information needed to process it
9   - Server doesn't store client state between requests
10   - Improves scalability and reliability
11
123. CACHEABILITY
13   - Responses must explicitly indicate if they're cacheable
14   - Improves performance and reduces server load
15   - Clients can reuse cached responses
16
174. UNIFORM INTERFACE
18   - Consistent way to interact with resources
19   - Standard HTTP methods and status codes
20   - Self-descriptive messages
21
225. LAYERED SYSTEM
23   - Client doesn't need to know if connected directly to server
24   - Supports load balancers, proxies, gateways
25   - Improves scalability and security
26
276. CODE ON DEMAND (Optional)
28   - Server can send executable code to client
29   - Examples: JavaScript, applets
30   - Extends client functionality
31*/
32
33// Example of RESTful resource design
34const apiDesign = {
35  // Resource identification through URIs
36  resources: {
37    users: '/api/v1/users',
38    userById: '/api/v1/users/{id}',
39    userOrders: '/api/v1/users/{id}/orders',
40    orders: '/api/v1/orders',
41    orderById: '/api/v1/orders/{id}',
42    products: '/api/v1/products',
43    productById: '/api/v1/products/{id}'
44  },
45
46  // Standard HTTP methods for different operations
47  methods: {
48    GET: 'Retrieve resource(s)',
49    POST: 'Create new resource',
50    PUT: 'Update/replace entire resource',
51    PATCH: 'Partially update resource',
52    DELETE: 'Remove resource',
53    HEAD: 'Get resource metadata only',
54    OPTIONS: 'Get allowed methods for resource'
55  },
56
57  // Standard HTTP status codes
58  statusCodes: {
59    // Success
60    200: 'OK - Request successful',
61    201: 'Created - Resource created',
62    202: 'Accepted - Request accepted for processing',
63    204: 'No Content - Successful but no response body',
64
65    // Client Errors
66    400: 'Bad Request - Invalid request syntax',
67    401: 'Unauthorized - Authentication required',
68    403: 'Forbidden - Access denied',
69    404: 'Not Found - Resource not found',
70    405: 'Method Not Allowed - HTTP method not supported',
71    409: 'Conflict - Resource conflict',
72    422: 'Unprocessable Entity - Validation error',
73    429: 'Too Many Requests - Rate limit exceeded',
74
75    // Server Errors
76    500: 'Internal Server Error - Generic server error',
77    502: 'Bad Gateway - Invalid response from upstream',
78    503: 'Service Unavailable - Server temporarily unavailable',
79    504: 'Gateway Timeout - Upstream timeout'
80  }
81};

1const express = require('express');
2const cors = require('cors');
3const helmet = require('helmet');
4const rateLimit = require('express-rate-limit');
5
6// Import route modules
7const userRoutes = require('./users');
8const productRoutes = require('./products');
9const orderRoutes = require('./orders');
10const categoryRoutes = require('./categories');
11
12// Import middleware
13const auth = require('../../../middleware/auth');
14const validation = require('../../../middleware/validation');
15const errorHandler = require('../../../middleware/errorHandler');
16const requestLogger = require('../../../middleware/requestLogger');
17
18class APIRouter {
19  constructor() {
20    this.router = express.Router();
21    this.setupMiddleware();
22    this.setupRoutes();
23    this.setupErrorHandling();
24  }
25
26  setupMiddleware() {
27    // Security middleware
28    this.router.use(helmet({
29      contentSecurityPolicy: false, // Allow for API usage
30      crossOriginResourcePolicy: { policy: "cross-origin" }
31    }));
32
33    // CORS configuration
34    this.router.use(cors({
35      origin: process.env.ALLOWED_ORIGINS?.split(',') || ['http://localhost:3000'],
36      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
37      allowedHeaders: [
38        'Content-Type',
39        'Authorization',
40        'X-Requested-With',
41        'X-API-Version',
42        'X-Client-Version'
43      ],
44      exposedHeaders: [
45        'X-Total-Count',
46        'X-Page-Count',
47        'X-Rate-Limit-Remaining',
48        'X-Rate-Limit-Reset'
49      ],
50      credentials: true,
51      maxAge: 86400 // 24 hours
52    }));
53
54    // Rate limiting
55    const limiter = rateLimit({
56      windowMs: 15 * 60 * 1000, // 15 minutes
57      max: 1000, // Limit each IP to 1000 requests per windowMs
58      message: {
59        error: 'Too many requests',
60        message: 'Rate limit exceeded. Please try again later.',
61        retryAfter: 900 // 15 minutes in seconds
62      },
63      standardHeaders: true,
64      legacyHeaders: false,
65      handler: (req, res) => {
66        res.status(429).json({
67          error: 'Too Many Requests',
68          message: 'Rate limit exceeded',
69          retryAfter: Math.round(req.rateLimit.resetTime / 1000)
70        });
71      }
72    });
73
74    this.router.use(limiter);
75
76    // Request parsing
77    this.router.use(express.json({ limit: '10mb' }));
78    this.router.use(express.urlencoded({ extended: true, limit: '10mb' }));
79
80    // Request logging
81    this.router.use(requestLogger);
82
83    // API versioning header validation
84    this.router.use((req, res, next) => {
85      const acceptedVersions = ['1.0', '1.1'];
86      const requestedVersion = req.headers['x-api-version'] || '1.0';
87
88      if (!acceptedVersions.includes(requestedVersion)) {
89        return res.status(400).json({
90          error: 'Unsupported API Version',
91          message: \`API version \${requestedVersion} is not supported\`,
92          supportedVersions: acceptedVersions
93        });
94      }
95
96      req.apiVersion = requestedVersion;
97      res.set('X-API-Version', requestedVersion);
98      next();
99    });
100  }
101
102  setupRoutes() {
103    // Health check endpoint
104    this.router.get('/health', (req, res) => {
105      res.json({
106        status: 'healthy',
107        timestamp: new Date().toISOString(),
108        version: process.env.API_VERSION || '1.0.0',
109        environment: process.env.NODE_ENV || 'development',
110        uptime: process.uptime()
111      });
112    });
113
114    // API documentation endpoint
115    this.router.get('/docs', (req, res) => {
116      res.json({
117        name: 'E-commerce API',
118        version: '1.0.0',
119        description: 'RESTful API for e-commerce platform',
120        documentation: '/api/v1/swagger',
121        endpoints: {
122          users: '/api/v1/users',
123          products: '/api/v1/products',
124          orders: '/api/v1/orders',
125          categories: '/api/v1/categories'
126        },
127        authentication: {
128          type: 'Bearer Token (JWT)',
129          header: 'Authorization: Bearer <token>'
130        },
131        rateLimit: {
132          requests: 1000,
133          window: '15 minutes'
134        }
135      });
136    });
137
138    // Resource routes
139    this.router.use('/users', userRoutes);
140    this.router.use('/products', productRoutes);
141    this.router.use('/orders', orderRoutes);
142    this.router.use('/categories', categoryRoutes);
143
144    // Catch unmatched routes
145    this.router.use('*', (req, res) => {
146      res.status(404).json({
147        error: 'Not Found',
148        message: \`The endpoint \${req.method} \${req.originalUrl} was not found\`,
149        suggestion: 'Check the API documentation at /api/v1/docs'
150      });
151    });
152  }
153
154  setupErrorHandling() {
155    this.router.use(errorHandler);
156  }
157
158  getRouter() {
159    return this.router;
160  }
161}
162
163module.exports = new APIRouter().getRouter();

1const express = require('express');
2const router = express.Router();
3const auth = require('../../../middleware/auth');
4const validation = require('../../../middleware/validation');
5const productController = require('../../../controllers/productController');
6const reviewController = require('../../../controllers/reviewController');
7
8/*
9RESOURCE NAMING CONVENTIONS:
10
111. Use nouns, not verbs
12   ✅ /products (good)
13   ❌ /getProducts (bad)
14
152. Use plural nouns for collections
16   ✅ /products (good)
17   ❌ /product (bad)
18
193. Use hierarchical structure for relationships
20   ✅ /products/123/reviews (good)
21   ❌ /productReviews?productId=123 (acceptable but not ideal)
22
234. Use lowercase and hyphens for multi-word resources
24   ✅ /product-categories (good)
25   ❌ /productCategories or /product_categories (bad)
26
275. Keep URLs short and intuitive
28   ✅ /products/123/variants (good)
29   ❌ /products/123/productVariants (bad)
30*/
31
32// Products Collection Endpoints
33// GET /api/v1/products - Get all products with filtering, sorting, pagination
34router.get('/',
35  validation.validateQueryParams('productList'),
36  productController.getProducts
37);
38
39// POST /api/v1/products - Create a new product
40router.post('/',
41  auth.requireAuth,
42  auth.requireRole(['admin', 'manager']),
43  validation.validateBody('createProduct'),
44  productController.createProduct
45);
46
47// Product Resource Endpoints
48// GET /api/v1/products/:id - Get specific product
49router.get('/:id',
50  validation.validateParams('productId'),
51  productController.getProductById
52);
53
54// PUT /api/v1/products/:id - Update entire product (replace)
55router.put('/:id',
56  auth.requireAuth,
57  auth.requireRole(['admin', 'manager']),
58  validation.validateParams('productId'),
59  validation.validateBody('updateProduct'),
60  productController.updateProduct
61);
62
63// PATCH /api/v1/products/:id - Partially update product
64router.patch('/:id',
65  auth.requireAuth,
66  auth.requireRole(['admin', 'manager']),
67  validation.validateParams('productId'),
68  validation.validateBody('patchProduct'),
69  productController.patchProduct
70);
71
72// DELETE /api/v1/products/:id - Delete product (soft delete)
73router.delete('/:id',
74  auth.requireAuth,
75  auth.requireRole(['admin']),
76  validation.validateParams('productId'),
77  productController.deleteProduct
78);
79
80// Product Variants (Nested Resource)
81// GET /api/v1/products/:id/variants - Get product variants
82router.get('/:id/variants',
83  validation.validateParams('productId'),
84  productController.getProductVariants
85);
86
87// POST /api/v1/products/:id/variants - Create product variant
88router.post('/:id/variants',
89  auth.requireAuth,
90  auth.requireRole(['admin', 'manager']),
91  validation.validateParams('productId'),
92  validation.validateBody('createVariant'),
93  productController.createProductVariant
94);
95
96// PUT /api/v1/products/:id/variants/:variantId - Update variant
97router.put('/:id/variants/:variantId',
98  auth.requireAuth,
99  auth.requireRole(['admin', 'manager']),
100  validation.validateParams('productVariantId'),
101  validation.validateBody('updateVariant'),
102  productController.updateProductVariant
103);
104
105// DELETE /api/v1/products/:id/variants/:variantId - Delete variant
106router.delete('/:id/variants/:variantId',
107  auth.requireAuth,
108  auth.requireRole(['admin', 'manager']),
109  validation.validateParams('productVariantId'),
110  productController.deleteProductVariant
111);
112
113// Product Reviews (Nested Resource)
114// GET /api/v1/products/:id/reviews - Get product reviews
115router.get('/:id/reviews',
116  validation.validateParams('productId'),
117  validation.validateQueryParams('reviewList'),
118  reviewController.getProductReviews
119);
120
121// POST /api/v1/products/:id/reviews - Create review for product
122router.post('/:id/reviews',
123  auth.requireAuth,
124  validation.validateParams('productId'),
125  validation.validateBody('createReview'),
126  reviewController.createProductReview
127);
128
129// Product Images (Nested Resource)
130// GET /api/v1/products/:id/images - Get product images
131router.get('/:id/images',
132  validation.validateParams('productId'),
133  productController.getProductImages
134);
135
136// POST /api/v1/products/:id/images - Upload product images
137router.post('/:id/images',
138  auth.requireAuth,
139  auth.requireRole(['admin', 'manager']),
140  validation.validateParams('productId'),
141  productController.uploadProductImages
142);
143
144// DELETE /api/v1/products/:id/images/:imageId - Delete product image
145router.delete('/:id/images/:imageId',
146  auth.requireAuth,
147  auth.requireRole(['admin', 'manager']),
148  validation.validateParams('productImageId'),
149  productController.deleteProductImage
150);
151
152// Bulk Operations
153// POST /api/v1/products/bulk - Bulk create products
154router.post('/bulk',
155  auth.requireAuth,
156  auth.requireRole(['admin']),
157  validation.validateBody('bulkCreateProducts'),
158  productController.bulkCreateProducts
159);
160
161// PATCH /api/v1/products/bulk - Bulk update products
162router.patch('/bulk',
163  auth.requireAuth,
164  auth.requireRole(['admin']),
165  validation.validateBody('bulkUpdateProducts'),
166  productController.bulkUpdateProducts
167);
168
169// Special Actions (Non-CRUD operations)
170// POST /api/v1/products/:id/duplicate - Duplicate a product
171router.post('/:id/duplicate',
172  auth.requireAuth,
173  auth.requireRole(['admin', 'manager']),
174  validation.validateParams('productId'),
175  productController.duplicateProduct
176);
177
178// POST /api/v1/products/:id/archive - Archive a product
179router.post('/:id/archive',
180  auth.requireAuth,
181  auth.requireRole(['admin', 'manager']),
182  validation.validateParams('productId'),
183  productController.archiveProduct
184);
185
186// POST /api/v1/products/:id/restore - Restore archived product
187router.post('/:id/restore',
188  auth.requireAuth,
189  auth.requireRole(['admin']),
190  validation.validateParams('productId'),
191  productController.restoreProduct
192);
193
194// Search endpoint (collection-level operation)
195// GET /api/v1/products/search?q=query - Search products
196router.get('/search',
197  validation.validateQueryParams('productSearch'),
198  productController.searchProducts
199);
200
201module.exports = router;

1const productService = require('../services/productService');
2const httpStatus = require('http-status');
3
4class ProductController {
5  // GET /api/v1/products - Retrieve products collection
6  async getProducts(req, res, next) {
7    try {
8      const {
9        page = 1,
10        limit = 20,
11        sortBy = 'createdAt',
12        sortOrder = 'desc',
13        category,
14        priceMin,
15        priceMax,
16        inStock,
17        featured,
18        search
19      } = req.query;
20
21      const filters = {
22        category,
23        priceRange: (priceMin || priceMax) ? { min: priceMin, max: priceMax } : null,
24        inStock: inStock !== undefined ? inStock === 'true' : null,
25        featured: featured !== undefined ? featured === 'true' : null,
26        search
27      };
28
29      const pagination = {
30        page: parseInt(page),
31        limit: parseInt(limit),
32        sortBy,
33        sortOrder
34      };
35
36      const result = await productService.getProducts(filters, pagination);
37
38      // Set pagination headers
39      res.set({
40        'X-Total-Count': result.pagination.totalCount.toString(),
41        'X-Page-Count': result.pagination.totalPages.toString(),
42        'X-Current-Page': result.pagination.currentPage.toString(),
43        'X-Per-Page': result.pagination.limit.toString()
44      });
45
46      // Add pagination links
47      const baseUrl = \`\${req.protocol}://\${req.get('Host')}\${req.baseUrl}\${req.path}\`;
48      const links = [];
49
50      if (result.pagination.hasPrevPage) {
51        links.push(\`<\${baseUrl}?page=\${result.pagination.currentPage - 1}&limit=\${limit}>; rel="prev"\`);
52        links.push(\`<\${baseUrl}?page=1&limit=\${limit}>; rel="first"\`);
53      }
54
55      if (result.pagination.hasNextPage) {
56        links.push(\`<\${baseUrl}?page=\${result.pagination.currentPage + 1}&limit=\${limit}>; rel="next"\`);
57        links.push(\`<\${baseUrl}?page=\${result.pagination.totalPages}&limit=\${limit}>; rel="last"\`);
58      }
59
60      if (links.length > 0) {
61        res.set('Link', links.join(', '));
62      }
63
64      // 200 OK - Successful retrieval
65      res.status(httpStatus.OK).json({
66        success: true,
67        data: result.products,
68        pagination: result.pagination,
69        filters: filters,
70        meta: {
71          timestamp: new Date().toISOString(),
72          version: req.apiVersion
73        }
74      });
75
76    } catch (error) {
77      next(error);
78    }
79  }
80
81  // POST /api/v1/products - Create new product
82  async createProduct(req, res, next) {
83    try {
84      const productData = {
85        ...req.body,
86        createdBy: req.user.id
87      };
88
89      const result = await productService.createProduct(productData);
90
91      // Set location header for newly created resource
92      res.set('Location', \`/api/v1/products/\${result.product.id}\`);
93
94      // 201 Created - Resource successfully created
95      res.status(httpStatus.CREATED).json({
96        success: true,
97        data: result.product,
98        message: 'Product created successfully',
99        meta: {
100          timestamp: new Date().toISOString(),
101          createdBy: req.user.email
102        }
103      });
104
105    } catch (error) {
106      if (error.name === 'ValidationError') {
107        // 422 Unprocessable Entity - Validation failed
108        return res.status(httpStatus.UNPROCESSABLE_ENTITY).json({
109          success: false,
110          error: 'Validation Error',
111          message: error.message,
112          details: error.details || {}
113        });
114      }
115
116      if (error.code === 'DUPLICATE_SKU') {
117        // 409 Conflict - Resource already exists
118        return res.status(httpStatus.CONFLICT).json({
119          success: false,
120          error: 'Conflict',
121          message: 'Product with this SKU already exists',
122          conflictField: 'sku'
123        });
124      }
125
126      next(error);
127    }
128  }
129
130  // GET /api/v1/products/:id - Retrieve specific product
131  async getProductById(req, res, next) {
132    try {
133      const { id } = req.params;
134      const { include } = req.query;
135
136      const includeOptions = {
137        variants: include?.includes('variants'),
138        reviews: include?.includes('reviews'),
139        category: include?.includes('category'),
140        images: include?.includes('images')
141      };
142
143      const result = await productService.getProductById(id, includeOptions);
144
145      if (!result.product) {
146        // 404 Not Found - Resource doesn't exist
147        return res.status(httpStatus.NOT_FOUND).json({
148          success: false,
149          error: 'Not Found',
150          message: \`Product with ID \${id} was not found\`
151        });
152      }
153
154      // Add caching headers for GET requests
155      res.set({
156        'Cache-Control': 'public, max-age=300', // 5 minutes
157        'ETag': \`"\${result.product.updatedAt}"\`,
158        'Last-Modified': new Date(result.product.updatedAt).toUTCString()
159      });
160
161      // Check if client has cached version
162      if (req.headers['if-none-match'] === \`"\${result.product.updatedAt}"\`) {
163        // 304 Not Modified - Client has current version
164        return res.status(httpStatus.NOT_MODIFIED).end();
165      }
166
167      // 200 OK - Successful retrieval
168      res.status(httpStatus.OK).json({
169        success: true,
170        data: result.product,
171        meta: {
172          timestamp: new Date().toISOString(),
173          included: includeOptions
174        }
175      });
176
177    } catch (error) {
178      next(error);
179    }
180  }
181
182  // PUT /api/v1/products/:id - Update entire product (replace)
183  async updateProduct(req, res, next) {
184    try {
185      const { id } = req.params;
186      const updateData = {
187        ...req.body,
188        updatedBy: req.user.id
189      };
190
191      const result = await productService.updateProduct(id, updateData, { replace: true });
192
193      if (!result.product) {
194        // 404 Not Found - Resource doesn't exist
195        return res.status(httpStatus.NOT_FOUND).json({
196          success: false,
197          error: 'Not Found',
198          message: \`Product with ID \${id} was not found\`
199        });
200      }
201
202      // 200 OK - Successful update
203      res.status(httpStatus.OK).json({
204        success: true,
205        data: result.product,
206        message: 'Product updated successfully',
207        meta: {
208          timestamp: new Date().toISOString(),
209          updatedBy: req.user.email,
210          operation: 'replace'
211        }
212      });
213
214    } catch (error) {
215      if (error.name === 'ValidationError') {
216        return res.status(httpStatus.UNPROCESSABLE_ENTITY).json({
217          success: false,
218          error: 'Validation Error',
219          message: error.message,
220          details: error.details || {}
221        });
222      }
223
224      next(error);
225    }
226  }
227
228  // PATCH /api/v1/products/:id - Partially update product
229  async patchProduct(req, res, next) {
230    try {
231      const { id } = req.params;
232      const updateData = {
233        ...req.body,
234        updatedBy: req.user.id
235      };
236
237      const result = await productService.updateProduct(id, updateData, { replace: false });
238
239      if (!result.product) {
240        return res.status(httpStatus.NOT_FOUND).json({
241          success: false,
242          error: 'Not Found',
243          message: \`Product with ID \${id} was not found\`
244        });
245      }
246
247      // 200 OK - Successful partial update
248      res.status(httpStatus.OK).json({
249        success: true,
250        data: result.product,
251        message: 'Product updated successfully',
252        meta: {
253          timestamp: new Date().toISOString(),
254          updatedBy: req.user.email,
255          operation: 'patch',
256          fieldsUpdated: Object.keys(req.body)
257        }
258      });
259
260    } catch (error) {
261      if (error.name === 'ValidationError') {
262        return res.status(httpStatus.UNPROCESSABLE_ENTITY).json({
263          success: false,
264          error: 'Validation Error',
265          message: error.message,
266          details: error.details || {}
267        });
268      }
269
270      next(error);
271    }
272  }
273
274  // DELETE /api/v1/products/:id - Delete product
275  async deleteProduct(req, res, next) {
276    try {
277      const { id } = req.params;
278      const { permanent = false } = req.query;
279
280      const result = await productService.deleteProduct(id, {
281        permanent: permanent === 'true',
282        deletedBy: req.user.id
283      });
284
285      if (!result.success) {
286        return res.status(httpStatus.NOT_FOUND).json({
287          success: false,
288          error: 'Not Found',
289          message: \`Product with ID \${id} was not found\`
290        });
291      }
292
293      if (permanent === 'true') {
294        // 204 No Content - Resource permanently deleted
295        res.status(httpStatus.NO_CONTENT).end();
296      } else {
297        // 200 OK - Resource soft deleted
298        res.status(httpStatus.OK).json({
299          success: true,
300          message: 'Product archived successfully',
301          meta: {
302            timestamp: new Date().toISOString(),
303            deletedBy: req.user.email,
304            permanent: false,
305            restoreEndpoint: \`/api/v1/products/\${id}/restore\`
306          }
307        });
308      }
309
310    } catch (error) {
311      if (error.code === 'CONSTRAINT_VIOLATION') {
312        // 409 Conflict - Cannot delete due to dependencies
313        return res.status(httpStatus.CONFLICT).json({
314          success: false,
315          error: 'Conflict',
316          message: 'Cannot delete product with existing orders',
317          suggestion: 'Archive the product instead or handle dependent records first'
318        });
319      }
320
321      next(error);
322    }
323  }
324
325  // HEAD /api/v1/products/:id - Get product metadata
326  async getProductMetadata(req, res, next) {
327    try {
328      const { id } = req.params;
329      const result = await productService.getProductMetadata(id);
330
331      if (!result.exists) {
332        return res.status(httpStatus.NOT_FOUND).end();
333      }
334
335      // Set headers without response body
336      res.set({
337        'Content-Type': 'application/json',
338        'Content-Length': JSON.stringify(result.metadata).length.toString(),
339        'Last-Modified': new Date(result.metadata.updatedAt).toUTCString(),
340        'ETag': \`"\${result.metadata.updatedAt}"\`
341      });
342
343      // 200 OK - Headers only, no body
344      res.status(httpStatus.OK).end();
345
346    } catch (error) {
347      next(error);
348    }
349  }
350
351  // OPTIONS /api/v1/products/:id - Get allowed methods
352  async getProductOptions(req, res, next) {
353    try {
354      const { id } = req.params;
355
356      // Check if resource exists
357      const exists = await productService.productExists(id);
358
359      if (!exists) {
360        return res.status(httpStatus.NOT_FOUND).end();
361      }
362
363      // Set allowed methods based on user permissions
364      let allowedMethods = ['GET', 'HEAD', 'OPTIONS'];
365
366      if (req.user) {
367        if (req.user.role === 'admin' || req.user.role === 'manager') {
368          allowedMethods.push('PUT', 'PATCH', 'DELETE');
369        }
370      }
371
372      res.set({
373        'Allow': allowedMethods.join(', '),
374        'Access-Control-Allow-Methods': allowedMethods.join(', ')
375      });
376
377      // 200 OK - Options response
378      res.status(httpStatus.OK).json({
379        allowedMethods,
380        endpoints: {
381          self: \`/api/v1/products/\${id}\`,
382          variants: \`/api/v1/products/\${id}/variants\`,
383          reviews: \`/api/v1/products/\${id}/reviews\`,
384          images: \`/api/v1/products/\${id}/images\`
385        }
386      });
387
388    } catch (error) {
389      next(error);
390    }
391  }
392}
393
394module.exports = new ProductController();

1class APIVersioningMiddleware {
2  constructor() {
3    this.supportedVersions = new Map([
4      ['1.0', {
5        released: '2024-01-01',
6        deprecated: null,
7        sunset: null,
8        features: ['basic-crud', 'authentication', 'pagination']
9      }],
10      ['1.1', {
11        released: '2024-06-01',
12        deprecated: null,
13        sunset: null,
14        features: ['basic-crud', 'authentication', 'pagination', 'search', 'bulk-operations']
15      }],
16      ['2.0', {
17        released: '2024-12-01',
18        deprecated: null,
19        sunset: null,
20        features: ['graphql', 'real-time', 'advanced-search', 'analytics']
21      }]
22    ]);
23
24    this.defaultVersion = '1.1';
25    this.deprecationWarnings = new Map([
26      ['1.0', 'API version 1.0 will be deprecated on 2025-06-01. Please upgrade to version 2.0.']
27    ]);
28  }
29
30  // Version detection middleware
31  detectVersion() {
32    return (req, res, next) => {
33      let version = this.defaultVersion;
34
35      // 1. Check Accept header version (preferred)
36      const acceptHeader = req.headers.accept;
37      if (acceptHeader && acceptHeader.includes('application/vnd.api+json')) {
38        const versionMatch = acceptHeader.match(/version=([0-9.]+)/);
39        if (versionMatch) {
40          version = versionMatch[1];
41        }
42      }
43
44      // 2. Check custom header
45      if (req.headers['x-api-version']) {
46        version = req.headers['x-api-version'];
47      }
48
49      // 3. Check URL path (last resort)
50      const pathVersionMatch = req.path.match(/\\/v([0-9.]+)\\//);
51      if (pathVersionMatch) {
52        version = pathVersionMatch[1];
53      }
54
55      // 4. Check query parameter (not recommended but supported)
56      if (req.query.version) {
57        version = req.query.version;
58      }
59
60      // Validate version
61      if (!this.supportedVersions.has(version)) {
62        return res.status(400).json({
63          error: 'Unsupported API Version',
64          message: \`API version \${version} is not supported\`,
65          supportedVersions: Array.from(this.supportedVersions.keys()),
66          currentVersion: this.defaultVersion
67        });
68      }
69
70      // Set version info
71      req.apiVersion = version;
72      req.versionInfo = this.supportedVersions.get(version);
73
74      // Set response headers
75      res.set({
76        'X-API-Version': version,
77        'X-API-Version-Released': req.versionInfo.released
78      });
79
80      // Add deprecation warning if applicable
81      if (this.deprecationWarnings.has(version)) {
82        res.set('X-API-Deprecation-Warning', this.deprecationWarnings.get(version));
83        res.set('X-API-Sunset-Date', req.versionInfo.sunset || 'TBD');
84      }
85
86      next();
87    };
88  }
89
90  // Version-specific feature checking
91  checkFeature(feature) {
92    return (req, res, next) => {
93      if (!req.versionInfo.features.includes(feature)) {
94        return res.status(404).json({
95          error: 'Feature Not Available',
96          message: \`Feature '\${feature}' is not available in API version \${req.apiVersion}\`,
97          availableIn: this.getVersionsWithFeature(feature),
98          upgradeRecommendation: this.getLatestVersionWithFeature(feature)
99        });
100      }
101      next();
102    };
103  }
104
105  // Version-specific response transformation
106  transformResponse(version, data) {
107    switch (version) {
108      case '1.0':
109        return this.transformToV1_0(data);
110      case '1.1':
111        return this.transformToV1_1(data);
112      case '2.0':
113        return this.transformToV2_0(data);
114      default:
115        return data;
116    }
117  }
118
119  transformToV1_0(data) {
120    // Legacy format for v1.0
121    if (Array.isArray(data)) {
122      return data.map(item => ({
123        id: item.id,
124        name: item.name,
125        price: item.price,
126        description: item.description,
127        // Remove newer fields not available in v1.0
128        created_at: item.createdAt,
129        updated_at: item.updatedAt
130      }));
131    }
132
133    return {
134      id: data.id,
135      name: data.name,
136      price: data.price,
137      description: data.description,
138      created_at: data.createdAt,
139      updated_at: data.updatedAt
140    };
141  }
142
143  transformToV1_1(data) {
144    // Enhanced format for v1.1
145    if (Array.isArray(data)) {
146      return data.map(item => ({
147        id: item.id,
148        name: item.name,
149        slug: item.slug,
150        price: item.price,
151        compareAtPrice: item.compareAtPrice,
152        description: item.description,
153        shortDescription: item.shortDescription,
154        category: item.category,
155        tags: item.tags,
156        images: item.images,
157        inStock: item.stockStatus === 'in_stock',
158        createdAt: item.createdAt,
159        updatedAt: item.updatedAt
160      }));
161    }
162
163    return {
164      id: data.id,
165      name: data.name,
166      slug: data.slug,
167      price: data.price,
168      compareAtPrice: data.compareAtPrice,
169      description: data.description,
170      shortDescription: data.shortDescription,
171      category: data.category,
172      tags: data.tags,
173      images: data.images,
174      inStock: data.stockStatus === 'in_stock',
175      createdAt: data.createdAt,
176      updatedAt: data.updatedAt
177    };
178  }
179
180  transformToV2_0(data) {
181    // Latest format with all features
182    return data; // No transformation needed for latest version
183  }
184
185  getVersionsWithFeature(feature) {
186    const versions = [];
187    for (const [version, info] of this.supportedVersions) {
188      if (info.features.includes(feature)) {
189        versions.push(version);
190      }
191    }
192    return versions;
193  }
194
195  getLatestVersionWithFeature(feature) {
196    const versions = this.getVersionsWithFeature(feature);
197    return versions.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))[0];
198  }
199
200  // Middleware to transform responses based on version
201  responseTransformer() {
202    return (req, res, next) => {
203      const originalJson = res.json;
204
205      res.json = (data) => {
206        // Transform data based on API version
207        const transformedData = this.transformResponse(req.apiVersion, data);
208
209        // Add version-specific metadata
210        const responseData = {
211          ...transformedData,
212          _meta: {
213            version: req.apiVersion,
214            timestamp: new Date().toISOString(),
215            requestId: req.id || 'unknown'
216          }
217        };
218
219        // Call original json method with transformed data
220        return originalJson.call(res, responseData);
221      };
222
223      next();
224    };
225  }
226
227  // Content negotiation based on version
228  contentNegotiation() {
229    return (req, res, next) => {
230      const accept = req.headers.accept || 'application/json';
231
232      // Set content type based on version and accept header
233      if (accept.includes('application/vnd.api+json')) {
234        res.set('Content-Type', \`application/vnd.api+json; version=\${req.apiVersion}\`);
235      } else if (accept.includes('application/hal+json') && req.apiVersion >= '2.0') {
236        res.set('Content-Type', 'application/hal+json');
237      } else {
238        res.set('Content-Type', 'application/json');
239      }
240
241      next();
242    };
243  }
244}
245
246module.exports = new APIVersioningMiddleware();