API contract và data model từ access patterns

API/data model là nơi requirements trở thành invariant, query và ownership cụ thể. Đừng bắt đầu bằng “tạo vài bảng rồi thêm CRUD”; hãy bắt đầu từ những hành vi quan trọng của hệ thống và những điều tuyệt đối không được phép sai.

1. API surface

Ở system design, cần chỉ định các critical endpoints hoặc events và contract quan trọng của chúng: request/response, auth context, error, idempotency, pagination và trạng thái của async operation. Stable IDs cùng version/ETag hỗ trợ retry và concurrency. Không cần liệt kê toàn bộ CRUD nếu chúng không giúp chứng minh design.

Critical contract nên trả lời gì?

Ví dụ contract tối thiểu

POST /orders
Authorization: Bearer ...
Idempotency-Key: 9fd2...

{
  "items": [{"sku":"A-17","quantity":2}],
  "shipping_address_id":"addr_42"
}

201 Created
ETag: "order-v1"
{
  "order_id":"ord_01...",
  "status":"PENDING",
  "created_at":"..."
}

Ví dụ trên chỉ minh họa cách nói rõ contract; endpoint, header và status cụ thể vẫn phải theo requirement của bài toán.

2. Access patterns

Với mỗi user/system journey, ghi rõ: key lookup, range query, sort/filter, write frequency và consistency. Từ dominant paths đó mới chọn primary key, partition key và index. Secondary index hoặc denormalization có thể làm read nhanh hơn nhưng đổi lại là write amplification, storage cost và consistency work.

Access-pattern matrix

3. Invariant và ownership

Xác định rõ source of truth, uniqueness, state machine và transaction scope. Ví dụ, “ledger append + derived balance” là model khác fundamentally so với “mutable balance”: model đầu lưu lịch sử biến động làm nguồn sự thật rồi derive số dư; model sau cập nhật trực tiếp một giá trị hiện tại.

Biến requirement thành invariant

• Uniqueness: một email unique toàn hệ thống, theo tenant, hay chỉ unique trong một account?
• State machine: order được phép đi từ PENDING → PAID → FULFILLED; transition nào bị cấm hoặc cần compensating action?
• Transaction scope: những row/document/aggregate nào phải cùng thành công hoặc cùng thất bại?
• Source of truth: record nào quyết định state cuối cùng khi cache, search index, projection hoặc analytics disagree?

Ownership là một phần của data model

Data ownership quyết định service boundary. Nếu hai service cùng sửa một shared table, boundary trên sơ đồ chỉ là autonomy giả: deploy, migration, authorization và failure vẫn bị coupling qua cùng schema. Một service có thể publish event/read model cho service khác, nhưng cần biết ai là writer/source of truth.

4. ID generation

Không có một chiến lược ID tốt nhất cho mọi workload. Nguồn nhấn mạnh bốn nhóm trade-off: auto-increment đơn giản nhưng centralized/predictable; UUID dễ sinh phân tán nhưng có cost về index locality/size; time-sortable IDs cải thiện locality nhưng mang timestamp/privacy/clock caveat; short code cần collision strategy và abuse controls.

ID không đồng nghĩa authorization

Dù ID là random UUID hay short opaque token, vẫn phải thực hiện authorization trên resource. “Khó đoán” chỉ làm enumeration khó hơn; nó không phải access control.

5. Evolution

Schema, API và event phải sống được trong giai đoạn mixed versions. Một rollout an toàn thường theo nhịp expand → deploy → backfill → switch → contract. Backfill cần throttle, checkpoint và reconciliation; cache/projection cũng cần versioning để tránh dữ liệu cũ và mới bị hiểu như cùng một schema.

Expand → deploy → backfill → switch → contract

API/event compatibility

• Ưu tiên additive change khi có nhiều consumer deploy độc lập.
• Không tái sử dụng cùng field với semantic khác chỉ để “đỡ tạo version mới”.
• Consumer nên tolerate field chưa biết nếu protocol cho phép.
• Cache key, search projection và materialized view cần gắn version/epoch khi interpretation thay đổi.
• Backfill không được coi là xong chỉ vì job “SUCCESS”; cần đối chiếu count/checksum/business invariant phù hợp.

6. Design review checklist

• Critical API/events đã nói rõ request/response, auth context, error và retry/idempotency chưa?
• Pagination và async operation status có contract cụ thể chưa?
• Mỗi dominant journey đã map thành lookup/range/sort/filter, write frequency và consistency requirement chưa?
• Primary/partition/index choice có giải thích bằng access pattern thay vì “best practice” chung chung chưa?
• Source of truth, uniqueness, state machine và transaction scope có explicit chưa?
• Mỗi data domain có owner rõ; có shared-table coupling bị che bởi service diagram không?
• ID strategy có trade-off về distribution, predictability, locality, privacy và collision/abuse chưa?
• Schema/API/event migration có mixed-version plan, backfill throttle/checkpoint/reconciliation và rollback chưa?