REST API Design Best Practices#

1
const express = require('express');
2
const app = express();
3

4
// GET all users
5
app.get('/api/users', async (req, res) => {
6
  try {
7
    const users = await User.find();
8
    res.json({
9
      success: true,
10
      count: users.length,
11
      data: users
12
    });
13
  } catch (err) {
14
    res.status(500).json({
15
      success: false,
16
      error: 'Server Error'
17
    });
18
  }
19
});
20

21
// GET single user
22
app.get('/api/users/:id', async (req, res) => {
23
  try {
24
    const user = await User.findById(req.params.id);
25

26
    if (!user) {
27
      return res.status(404).json({
28
        success: false,
29
        error: 'User not found'
30
      });
31
    }
32

33
    res.json({ success: true, data: user });
34
  } catch (err) {
35
    res.status(500).json({ success: false, error: 'Server Error' });
36
  }
37
});
38

39
// POST create user
40
app.post('/api/users', async (req, res) => {
41
  try {
42
    const user = await User.create(req.body);
43
    res.status(201).json({
44
      success: true,
45
      data: user
46
    });
47
  } catch (err) {
48
    res.status(400).json({
49
      success: false,
50
      error: err.message
51
    });
52
  }
53
});

1
{
2
  "success": true,
3
  "count": 2,
4
  "data": [
5
    { "id": 1, "name": "User 1" },
6
    { "id": 2, "name": "User 2" }
7
  ]
8
}

1
{
2
  "success": false,
3
  "error": "User not found"
4
}

1
GET /api/users?page=1&limit=10
2

3
Response:
4
{
5
  "success": true,
6
  "count": 10,
7
  "total": 100,
8
  "page": 1,
9
  "pages": 10,
10
  "data": [...]
11
}

1
GET /api/products?category=electronics&price[lte]=1000
2
GET /api/posts?sort=-createdAt
3
GET /api/users?fields=name,email

1
// Middleware
2
const protect = async (req, res, next) => {
3
  let token;
4

5
  if (req.headers.authorization?.startsWith('Bearer')) {
6
    token = req.headers.authorization.split(' ')[1];
7
  }
8

9
  if (!token) {
10
    return res.status(401).json({
11
      success: false,
12
      error: 'Not authorized'
13
    });
14
  }
15

16
  try {
17
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
18
    req.user = await User.findById(decoded.id);
19
    next();
20
  } catch (err) {
21
    res.status(401).json({ success: false, error: 'Not authorized' });
22
  }
23
};
24

25
// Protected route
26
app.get('/api/profile', protect, getProfile);

1
/api/v1/users
2
/api/v2/users

1
paths:
2
  /users:
3
    get:
4
      summary: Get all users
5
      responses:
6
        200:
7
          description: Success