HTTP Methods Semantics

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# Basic GET request
GET /users/12345 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1...
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=300
ETag: "a1b2c3d4"
 
{
    "id": "12345",
    "name": "Alice Chen",
    "email": "alice@example.com"
}
 
 
# Conditional GET (bandwidth efficient)
GET /users/12345 HTTP/1.1
Host: api.example.com
If-None-Match: "a1b2c3d4"
 
# Response when unchanged
HTTP/1.1 304 Not Modified
ETag: "a1b2c3d4"
 
 
# GET collection with query parameters
GET /users?role=admin&status=active&sort=-created&page=1&limit=20 HTTP/1.1
Accept: application/json
 
 
# Response with pagination
HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 145
 
{
    "data": [...],
    "_links": {
        "self": "/users?page=1&limit=20",
        "next": "/users?page=2&limit=20"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

// POST /users - Create a new user
app.post('/users', validateBody(createUserSchema), async (req, res) => {
    // Validate unique constraints
    const existing = await userRepository.findByEmail(req.body.email);
    if (existing) {
        return res.status(409).json({
            error: 'CONFLICT',
            message: 'A user with this email already exists',
            field: 'email'
        });
    }
 
    // Create the resource
    const user = await userRepository.create({
        name: req.body.name,
        email: req.body.email,
        role: req.body.role || 'user'
    });
 
    // 201 Created with Location header
    res.status(201)
        .header('Location', `/users/${user.id}`)
        .json({
            id: user.id,
            name: user.name,
            email: user.email,
            role: user.role,
            createdAt: user.createdAt,
            _links: {
                self: { href: `/users/${user.id}` }
            }
        });
});
 
 
// POST for async processing (202 Accepted)
app.post('/reports/generate', async (req, res) => {
    const job = await jobQueue.enqueue({
        type: 'report_generation',
        params: req.body
    });
 
    // Return immediately with job reference
    res.status(202).json({
        jobId: job.id,
        status: 'queued',
        estimatedCompletion: job.estimatedCompletion,
        _links: {
            status: { href: `/jobs/${job.id}` },
            cancel: { href: `/jobs/${job.id}`, method: 'DELETE' }
        }
    });
});
 
 
// POST with idempotency key (client-provided)
app.post('/payments', async (req, res) => {
    const idempotencyKey = req.headers['idempotency-key'];
    
    if (idempotencyKey) {
        const existing = await paymentRepository.findByIdempotencyKey(idempotencyKey);
        if (existing) {
            // Return the same response as before (idempotent behavior)
            return res.status(200).json(existing);
        }
    }
 
    const payment = await paymentService.process({
        ...req.body,
        idempotencyKey
    });
 
    res.status(201).json(payment);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// PUT /users/:id - Complete replacement
app.put('/users/:id', validateBody(fullUserSchema), async (req, res) => {
    // Validate all required fields are present (PUT requires completeness)
    const requiredFields = ['name', 'email', 'role', 'status'];
    const missing = requiredFields.filter(f => !(f in req.body));
    
    if (missing.length > 0) {
        return res.status(400).json({
            error: 'VALIDATION_ERROR',
            message: 'PUT requires all fields to be specified',
            missingFields: missing
        });
    }
 
    const user = await userRepository.findById(req.params.id);
    
    if (!user) {
        // PUT can create at a known URI (201 Created)
        const newUser = await userRepository.create({
            id: req.params.id,  // Use client-specified ID
            ...req.body
        });
        return res.status(201)
            .header('Location', `/users/${newUser.id}`)
            .json(newUser);
    }
 
    // Complete replacement (200 OK)
    const updatedUser = await userRepository.replace(req.params.id, req.body);
    res.json(updatedUser);
});
 
 
// PUT with optimistic locking (avoiding lost updates)
app.put('/documents/:id', async (req, res) => {
    const ifMatch = req.headers['if-match'];
    const document = await documentRepository.findById(req.params.id);
    
    if (!document) {
        return res.status(404).json({ error: 'NOT_FOUND' });
    }
 
    // Check version matches (ETag)
    if (ifMatch && ifMatch !== `"${document.version}"`) {
        return res.status(412).json({
            error: 'PRECONDITION_FAILED',
            message: 'Document has been modified since you last fetched it',
            currentVersion: document.version,
            yourVersion: ifMatch.replace(/"/g, '')
        });
    }
 
    const updated = await documentRepository.replace(req.params.id, {
        ...req.body,
        version: document.version + 1
    });
 
    res.header('ETag', `"${updated.version}"`)
       .json(updated);
});
 
 
// PUT for singleton resources (one per parent)
app.put('/users/:userId/preferences', async (req, res) => {
    // Preferences is a singleton - always exists once user exists
    const user = await userRepository.findById(req.params.userId);
    if (!user) {
        return res.status(404).json({ error: 'User not found' });
    }
 
    // Create or replace entirely
    const preferences = await preferencesRepository.upsert(
        req.params.userId,
        req.body
    );
 
    res.json(preferences);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# 1. MERGE PATCH (RFC 7396) - Simple and common
# Content-Type: application/merge-patch+json
# Send only the fields you want to update
 
PATCH /users/12345 HTTP/1.1
Content-Type: application/merge-patch+json
 
{
    "email": "new.email@example.com",
    "phone": null
}
 
# Result: email changed, phone removed, other fields unchanged
 
 
# 2. JSON PATCH (RFC 6902) - Precise operations
# Content-Type: application/json-patch+json
# Explicit operations: add, remove, replace, move, copy, test
 
PATCH /users/12345 HTTP/1.1
Content-Type: application/json-patch+json
 
[
    { "op": "replace", "path": "/email", "value": "new.email@example.com" },
    { "op": "remove", "path": "/phone" },
    { "op": "add", "path": "/tags/-", "value": "premium" },
    { "op": "test", "path": "/status", "value": "active" }
]
 
# "test" operation makes the whole patch fail if condition not met
# This enables atomic conditional updates
 
 
# 3. Custom business-oriented patch
PATCH /orders/ord-456 HTTP/1.1
Content-Type: application/json
 
{
    "operations": [
        { "action": "updateShippingAddress", "address": {...} },
        { "action": "applyDiscount", "code": "SUMMER20" }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// PATCH /users/:id - Merge patch implementation
app.patch('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    
    if (!user) {
        return res.status(404).json({ error: 'NOT_FOUND' });
    }
 
    // Whitelist patchable fields (security!)
    const patchableFields = ['name', 'email', 'phone', 'bio', 'avatar'];
    const updates: Record<string, any> = {};
    
    for (const field of patchableFields) {
        if (field in req.body) {
            updates[field] = req.body[field]; // null is valid (removes field)
        }
    }
 
    // Reject attempts to patch protected fields
    const protectedFields = ['id', 'createdAt', 'role', 'password'];
    const attemptedProtected = protectedFields.filter(f => f in req.body);
    
    if (attemptedProtected.length > 0) {
        return res.status(400).json({
            error: 'VALIDATION_ERROR',
            message: 'Cannot update protected fields',
            protectedFields: attemptedProtected
        });
    }
 
    const updatedUser = await userRepository.update(req.params.id, updates);
    res.json(updatedUser);
});
 
 
// Making PATCH idempotent with absolute values
// ❌ NOT IDEMPOTENT
app.patch('/counters/:id/increment', async (req, res) => {
    await db.query('UPDATE counters SET value = value + 1 WHERE id = ?', [req.params.id]);
    // Multiple requests = multiple increments
});
 
// ✅ IDEMPOTENT
app.patch('/counters/:id', async (req, res) => {
    // Absolute value, not relative
    await db.query('UPDATE counters SET value = ? WHERE id = ?', [req.body.value, req.params.id]);
    // Multiple identical requests = same result
});
 
 
// JSON Patch with the 'fast-json-patch' library
import * as jsonpatch from 'fast-json-patch';
 
app.patch('/documents/:id', async (req, res) => {
    const contentType = req.headers['content-type'];
    const document = await documentRepository.findById(req.params.id);
    
    if (!document) {
        return res.status(404).json({ error: 'NOT_FOUND' });
    }
 
    let patchedDocument;
 
    if (contentType === 'application/json-patch+json') {
        // RFC 6902 JSON Patch
        const errors = jsonpatch.validate(req.body, document.content);
        if (errors) {
            return res.status(400).json({ 
                error: 'INVALID_PATCH', 
                details: errors 
            });
        }
        
        patchedDocument = jsonpatch.applyPatch(
            jsonpatch.deepClone(document.content),
            req.body
        ).newDocument;
    } else {
        // Default: merge patch
        patchedDocument = { ...document.content, ...req.body };
    }
 
    const saved = await documentRepository.update(req.params.id, patchedDocument);
    res.json(saved);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// DELETE /users/:id - Simple hard delete
app.delete('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    
    // Approach 1: Return 204 regardless (emphasize idempotency)
    if (!user) {
        return res.status(204).send();
    }
    
    await userRepository.delete(req.params.id);
    res.status(204).send();
});
 
 
// DELETE with soft delete (common in production)
app.delete('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    
    if (!user) {
        return res.status(404).json({ error: 'NOT_FOUND' });
    }
 
    // Instead of physical deletion, mark as deleted
    await userRepository.update(req.params.id, {
        deletedAt: new Date(),
        status: 'deleted'
    });
 
    // Optionally return 200 with deletion details
    res.status(200).json({
        id: req.params.id,
        deleted: true,
        deletedAt: new Date().toISOString(),
        recoverable: true,
        recoverUntil: addDays(new Date(), 30).toISOString()
    });
});
 
 
// DELETE with cascade (document relationships)
app.delete('/projects/:projectId', async (req, res) => {
    const project = await projectRepository.findById(req.params.projectId);
    
    if (!project) {
        return res.status(204).send();
    }
 
    // Check for blocking constraints
    const activeMembers = await memberRepository.countByProject(req.params.projectId);
    
    if (activeMembers > 0 && !req.query.force) {
        return res.status(409).json({
            error: 'CONFLICT',
            message: 'Cannot delete project with active members',
            memberCount: activeMembers,
            hint: 'Add ?force=true to delete with all members'
        });
    }
 
    // Cascade delete in transaction
    await db.transaction(async (tx) => {
        await tx.delete('project_members').where('project_id', req.params.projectId);
        await tx.delete('projects').where('id', req.params.projectId);
    });
 
    res.status(204).send();
});
 
 
// DELETE collection subset (batch delete)
// DELETE /notifications?read=true&older_than=2024-01-01
app.delete('/notifications', async (req, res) => {
    const filter = {
        userId: req.user.id,
        read: req.query.read === 'true' ? true : undefined,
        createdBefore: req.query.older_than
    };
 
    const deletedCount = await notificationRepository.deleteWhere(filter);
 
    res.status(200).json({
        deleted: deletedCount,
        filter: filter
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// Proper CORS handling for REST APIs
 
// Middleware for OPTIONS preflight
app.options('*', (req, res) => {
    const origin = req.headers.origin;
    const allowedOrigins = [
        'https://webapp.example.com',
        'https://admin.example.com'
    ];
 
    if (allowedOrigins.includes(origin)) {
        res.header('Access-Control-Allow-Origin', origin);
        res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
        res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Request-ID');
        res.header('Access-Control-Max-Age', '86400'); // Cache preflight for 24h
        res.header('Access-Control-Allow-Credentials', 'true');
    }
 
    res.status(204).send();
});
 
// HEAD handler example
app.head('/files/:fileId', async (req, res) => {
    const file = await fileRepository.findById(req.params.fileId);
    
    if (!file) {
        return res.status(404).send();
    }
 
    // Return headers only, no body
    res.header('Content-Type', file.mimeType);
    res.header('Content-Length', file.size);
    res.header('ETag', `"${file.checksum}"`);
    res.header('Last-Modified', file.updatedAt.toUTCString());
    res.header('Accept-Ranges', 'bytes');
    res.status(200).send();
});
 
// Express: HEAD is automatically handled for GET routes
// If you define GET /users/:id, HEAD /users/:id works automatically