API Contract — Contract-first vs Code-first

API Contract là bản đặc tả chính thức mô tả API có những endpoint nào, nhận tham số gì, trả về dữ liệu dạng gì — thường viết bằng chuẩn OpenAPI (trước đây gọi là Swagger). Bản đặc tả này trở thành "nguồn sự thật" (source of truth) mà cả backend lẫn frontend/mobile cùng dựa vào, thay vì phải hỏi nhau qua lại hoặc đọc code của nhau.

Hai cách tiếp cận

Code-first (viết code trước, sinh contract sau)

Backend implement endpoint bình thường, rồi dùng annotation/reflection để tự động sinh ra tài liệu OpenAPI từ code.

• Ưu điểm: nhanh, phù hợp prototype/team nhỏ, không cần bước thiết kế riêng, contract luôn khớp với code (vì sinh ra từ code).
• Nhược điểm: tài liệu dễ "trễ" so với thực tế nếu quên cập nhật annotation, dễ bỏ sót các trường hợp biên vì thiết kế API là hệ quả phụ của việc viết code, không phải chủ đích.

Contract-first (thiết kế contract trước, code sau)

Viết đặc tả OpenAPI trước khi code — contract trở thành tài liệu được thống nhất, versioned, và dùng để sinh code stub, tài liệu, test tự động.

• Ưu điểm: frontend/mobile có thể bắt đầu code song song ngay khi có contract (dùng mock server dựng từ contract), không cần đợi backend implement xong; phát hiện breaking change ngay ở bước thiết kế thay vì phát hiện lúc chạy production.
• Nhược điểm: cần thêm 1 bước thiết kế/thống nhất trước khi code, chậm hơn với dự án nhỏ 1 người làm cả 2 phía.

Khi nào chọn cách nào

Quy tắc thực tế: API càng có nhiều consumer, và bạn càng ít kiểm soát được các consumer đó, thì contract-first càng đáng giá.

• 1 dev làm cả backend lẫn frontend, dự án nhỏ → code-first là đủ, không cần thêm quy trình.
• Nhiều team (backend, mobile, frontend web) làm song song, hoặc API public cho bên thứ 3 dùng → contract-first giúp các team không phải chờ nhau, và tránh việc 1 thay đổi nhỏ ở backend làm vỡ app mobile đang chạy production.

Swagger/OpenAPI trong thực tế

Dù chọn code-first hay contract-first, kết quả cuối cùng nên có 1 tài liệu OpenAPI đầy đủ — nó phục vụ 3 việc cùng lúc: tài liệu cho người đọc (Swagger UI), nguồn sinh code client tự động, và nguồn để công cụ test (như Bruno, Postman) import thành bộ collection test sẵn — đây chính là lý do plan có bước "Swagger API Documentation" và "Bruno API Collection" đi liền nhau: Bruno collection thường được build/generate dựa trên chính bản đặc tả OpenAPI đó.