HATEOAS: Hypermedia-Driven APIs

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

// Order in "pending_payment" state - what can we do?
{
    "orderId": "ord-123",
    "status": "pending_payment",
    "total": 99.99,
    "_links": {
        "self": {"href": "/orders/ord-123"},
        "pay": {"href": "/orders/ord-123/payments", "method": "POST"},
        "cancel": {"href": "/orders/ord-123/cancellations", "method": "POST"},
        "modify": {"href": "/orders/ord-123/items", "method": "PATCH"}
    }
}
 
// Same order after payment - available actions changed
{
    "orderId": "ord-123",
    "status": "paid",
    "total": 99.99,
    "_links": {
        "self": {"href": "/orders/ord-123"},
        "track": {"href": "/orders/ord-123/shipments"},
        "invoice": {"href": "/orders/ord-123/invoice"},
        "refund": {"href": "/orders/ord-123/refunds", "method": "POST"}
    }
}
// Notice: "cancel" and "modify" are gone; new actions appeared
// Client doesn't need to know order state machine logic
 
// Same order after shipping - even fewer (different) actions
{
    "orderId": "ord-123",
    "status": "shipped",
    "_links": {
        "self": {"href": "/orders/ord-123"},
        "track": {"href": "/orders/ord-123/shipments"},
        "return": {"href": "/orders/ord-123/returns", "method": "POST"},
        "review": {"href": "/orders/ord-123/reviews", "method": "POST"}
    }
}

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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

// Link generation based on resource state
 
interface Link {
    href: string;
    method?: string;
    title?: string;
    templated?: boolean;
}
 
interface OrderLinks {
    self: Link;
    pay?: Link;
    cancel?: Link;
    track?: Link;
    refund?: Link;
    invoice?: Link;
    items: Link;
    customer: Link;
}
 
class Order {
    id: string;
    status: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled';
    customerId: string;
    // ... other fields
 
    // Encapsulate link generation based on business rules
    getLinks(): OrderLinks {
        const links: OrderLinks = {
            self: { href: `/orders/${this.id}` },
            items: { href: `/orders/${this.id}/items` },
            customer: { href: `/customers/${this.customerId}` }
        };
 
        // Conditional links based on current state
        switch (this.status) {
            case 'pending':
                links.pay = { 
                    href: `/orders/${this.id}/payments`, 
                    method: 'POST',
                    title: 'Submit payment'
                };
                links.cancel = { 
                    href: `/orders/${this.id}/cancellations`, 
                    method: 'POST',
                    title: 'Cancel this order'
                };
                break;
 
            case 'paid':
                links.track = { href: `/orders/${this.id}/shipments` };
                links.invoice = { href: `/orders/${this.id}/invoice` };
                // Refund only within policy window
                if (this.isWithinRefundWindow()) {
                    links.refund = { 
                        href: `/orders/${this.id}/refunds`, 
                        method: 'POST' 
                    };
                }
                break;
 
            case 'shipped':
                links.track = { href: `/orders/${this.id}/shipments` };
                links.invoice = { href: `/orders/${this.id}/invoice` };
                break;
        }
 
        return links;
    }
 
    toHAL(): object {
        return {
            orderId: this.id,
            status: this.status,
            total: this.total,
            createdAt: this.createdAt,
            _links: this.getLinks()
        };
    }
 
    private isWithinRefundWindow(): boolean {
        const refundWindowDays = 30;
        const daysSincePaid = (Date.now() - this.paidAt.getTime()) / (1000 * 60 * 60 * 24);
        return daysSincePaid <= refundWindowDays;
    }
}
 
 
// Express handler returning HAL response
app.get('/orders/:id', async (req, res) => {
    const order = await orderRepository.findById(req.params.id);
    
    if (!order) {
        return res.status(404).json({
            error: 'NOT_FOUND',
            _links: {
                orders: { href: '/orders', title: 'Browse all orders' }
            }
        });
    }
 
    res.type('application/hal+json')
       .json(order.toHAL());
});
 
 
// Collection with pagination links
app.get('/orders', async (req, res) => {
    const page = parseInt(req.query.page) || 1;
    const limit = parseInt(req.query.limit) || 20;
    
    const { orders, total } = await orderRepository.findPaginated({
        userId: req.user.id,
        page,
        limit
    });
 
    const totalPages = Math.ceil(total / limit);
 
    res.type('application/hal+json').json({
        _embedded: {
            orders: orders.map(o => o.toHAL())
        },
        _links: {
            self: { href: `/orders?page=${page}&limit=${limit}` },
            first: { href: `/orders?page=1&limit=${limit}` },
            ...(page > 1 && { prev: { href: `/orders?page=${page - 1}&limit=${limit}` } }),
            ...(page < totalPages && { next: { href: `/orders?page=${page + 1}&limit=${limit}` } }),
            last: { href: `/orders?page=${totalPages}&limit=${limit}` },
            create: { href: '/orders', method: 'POST', title: 'Create new order' }
        },
        page: { current: page, total: totalPages, size: limit, totalItems: total }
    });
});

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

// Standard IANA relations
const standardLinks = {
    // Navigation
    self: { href: '/orders/ord-123' },
    collection: { href: '/orders' },
    
    // Pagination (when applicable)
    first: { href: '/orders?page=1' },
    prev: { href: '/orders?page=2' },
    next: { href: '/orders?page=4' },
    last: { href: '/orders?page=10' }
};
 
 
// Custom relations with documentation (CURIEs)
// CURIEs let you define custom relations with documentation links
const responseWithCuries = {
    orderId: 'ord-123',
    status: 'pending',
    _links: {
        // CURIE definition
        curies: [
            {
                name: 'acme',
                href: 'https://docs.acme.com/rels/{rel}',
                templated: true
            }
        ],
        
        // Standard relations (no prefix needed)
        self: { href: '/orders/ord-123' },
        collection: { href: '/orders' },
        
        // Custom relations (prefixed with CURIE name)
        'acme:cancel': { href: '/orders/ord-123/cancellations', method: 'POST' },
        'acme:pay': { href: '/orders/ord-123/payments', method: 'POST' },
        'acme:expedite': { href: '/orders/ord-123/expedite', method: 'POST' }
        
        // Clients can look up 'acme:cancel' at:
        // https://docs.acme.com/rels/cancel
    }
};
 
 
// Best practice: Use standard relations when possible
// Prefix custom relations to avoid conflicts
 
interface LinkRelations {
    // Standard (IANA)
    self: Link;
    collection?: Link;
    next?: Link;
    prev?: Link;
    first?: Link;
    last?: Link;
    
    // Domain-specific (custom, but common patterns)
    cancel?: Link;     // Cancel a pending action
    pay?: Link;        // Submit payment
    refund?: Link;     // Request refund
    track?: Link;      // Track shipment/status
    invoice?: Link;    // View invoice
    receipt?: Link;    // View receipt
    
    // Relationship links
    customer?: Link;   // Related customer
    items?: Link;      // Related items collection
    order?: Link;      // Parent order (from item)
}

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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

// Hypermedia-aware API client
 
class HypermediaClient {
    private baseUrl: string;
    private token: string;
 
    async get(url: string): Promise<HalResource> {
        const response = await fetch(this.baseUrl + url, {
            headers: { 
                'Accept': 'application/hal+json',
                'Authorization': `Bearer ${this.token}`
            }
        });
        return response.json();
    }
 
    async follow(link: Link, body?: object): Promise<HalResource> {
        const response = await fetch(this.baseUrl + link.href, {
            method: link.method || 'GET',
            headers: {
                'Accept': 'application/hal+json',
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: body ? JSON.stringify(body) : undefined
        });
        return response.json();
    }
}
 
 
// Usage: Client follows links, never constructs URLs
class OrderService {
    constructor(private client: HypermediaClient) {}
 
    async cancelOrder(orderId: string, reason: string): Promise<void> {
        // Step 1: Fetch the order
        const order = await this.client.get(`/orders/${orderId}`);
 
        // Step 2: Check if cancellation is available
        const cancelLink = order._links?.cancel;
        
        if (!cancelLink) {
            throw new Error(
                'This order cannot be cancelled. ' +
                `Current status: ${order.status}`
            );
        }
 
        // Step 3: Follow the cancel link
        await this.client.follow(cancelLink, { reason });
    }
 
    async payForOrder(orderId: string, paymentDetails: PaymentDetails): Promise<void> {
        const order = await this.client.get(`/orders/${orderId}`);
 
        const payLink = order._links?.pay;
        
        if (!payLink) {
            if (order.status === 'paid') {
                throw new Error('Order is already paid');
            }
            throw new Error('Payment is not available for this order');
        }
 
        await this.client.follow(payLink, paymentDetails);
    }
}
 
 
// React component consuming hypermedia
function OrderActions({ order }: { order: HalOrder }) {
    const links = order._links;
 
    return (
        <div className="order-actions">
            {/* Only render buttons for available actions */}
            
            {links.pay && (
                <button onClick={() => handlePay(links.pay)}>
                    Pay Now
                </button>
            )}
            
            {links.cancel && (
                <button onClick={() => handleCancel(links.cancel)}>
                    Cancel Order
                </button>
            )}
            
            {links.track && (
                <a href={links.track.href}>
                    Track Shipment
                </a>
            )}
            
            {links.refund && (
                <button onClick={() => handleRefund(links.refund)}>
                    Request Refund
                </button>
            )}
            
            {/* UI adapts automatically based on available links */}
        </div>
    );
}