API không versioning – Update field name khiến 5 hệ thống sập theo

Đổi field user_id thành id, có sao đâu, ai ngờ đối tác sập hết!

Một công ty logistics Việt Nam update API, đổi field user_id thành id để “đẹp code”. Kết quả? 5 đối tác tích hợp (app, website, ERP) đồng loạt lỗi 500, khách hàng phàn nàn, team mất 2 tuần fix khẩn cấp.

Case thực tế: API “phá đảo” đối tác

• Context: API logistics, cung cấp tracking đơn hàng, tích hợp với 5 đối tác. 
• Quyết định sai: Update API v1, đổi user_id thành id mà không giữ backward compatibility. 
• Vấn đề: 
  • Đối tác dùng user_id trong code, API mới trả id, gây lỗi parsing. 
  • Không có versioning (VD: /v1/orders), đối tác không biết API đã đổi. 
  • Không thông báo trước cho đối tác.

Hậu quả: 

• Hệ thống sập: 5 đối tác lỗi 500, tracking không hoạt động. 
• Khách hàng bực: Phàn nàn vì không tra được đơn hàng. 
• Chi phí fix: Team làm việc 24/7, rollback API, tốn 100 triệu đồng.

Phân tích: Tại sao lại sai?

• Không versioning: API không có /v1, /v2, mọi update phá vỡ client. 
• Thiếu backward compatibility: Đổi field name mà không hỗ trợ cả cũ và mới. 
• Không thông báo: Đối tác không được cảnh báo về breaking change.

Bài học: Versioning và compatibility

1. API versioning: Dùng /v1, /v2 hoặc header Accept-Version. 
2. Backward compatibility: Hỗ trợ field cũ trong 6–12 tháng. 
3. Thông báo sớm: Gửi changelog, deprecation notice cho đối tác.

Code mẫu: API versioning (Express)

// routes/v1/orders.js
router.get('/v1/orders', (req, res) => {
    res.json({ id: 123, user_id: 123 }); // Hỗ trợ cả id và user_id
});

Góc nhìn CTO

API không versioning là “mời gọi thảm họa”. Luôn dùng versioning, giữ backward compatibility, và thông báo sớm để đối tác không “chửi” bạn lúc nửa đêm!

Checklist API design: 

• Dùng versioning (/v1, /v2). 
• Hỗ trợ backward compatibility 6–12 tháng. 
• Gửi changelog cho đối tác trước update. 
• Test với client cũ trước khi release.

🎯 Tóm lại: Không versioning API là “tự bắn vào chân”. Dùng /v1, giữ field cũ, để đối tác không sập và bạn không bị “chửi”!