API & Technical Literacy

API là gì?

Màn hình bạn đang thiết kế hầu như không tự có dữ liệu nào. Nó phải đi hỏi một nơi khác — backend của chính công ty, hoặc hệ thống của một nhà cung cấp bên ngoài như đơn vị vận chuyển hay ví điện tử.

API là cái cửa để hỏi đó: một danh sách những câu hỏi mà bên kia chấp nhận trả lời, kèm quy định câu hỏi phải viết thế nào và câu trả lời sẽ có dạng gì. Mỗi lượt trao đổi gồm đúng hai nửa:

• Request — câu hỏi đi ra: "cho tôi 20 đơn gần nhất của người dùng 8842".
• Response — câu trả lời đi về: hoặc là dữ liệu, hoặc là một thông báo lỗi.

Hai hệ quả mà mọi BA/PO cần mang theo suốt phần còn lại của trang này: lượt hỏi đó mất thời gian thật và có thể thất bại, và bạn chỉ hiển thị được đúng những gì bên kia trả về — thiết kế có vẽ số điện thoại người nhận mà response không chứa nó thì màn hình không thể có nó.

Baseline — bạn hiểu

• Hai hệ thống nói chuyện bằng request và response: một bên hỏi, bên kia trả về dữ liệu hoặc lỗi.
• Một lượt gọi có thể chậm, có thể thất bại — đó là chuyện bình thường, không phải trường hợp hiếm.
• Màn hình chỉ hiển thị được dữ liệu mà bên kia thật sự cung cấp; muốn thêm một trường mới thì phải hỏi bên kia có trường đó không.

Working — bạn làm được

• Với mỗi mẩu dữ liệu trên màn hình, nói được nó đến từ đâu: đã có sẵn trong hệ thống, phải gọi nhà cung cấp, hay được tính ra từ dữ liệu khác.
• Viết đủ ba trạng thái cho mọi màn hình lấy dữ liệu: đang tải, thành công, thất bại — kèm câu chữ và lối đi tiếp cho trạng thái thất bại.
• Nhận ra một thiết kế đang gọi dữ liệu quá thường xuyên và nêu vấn đề trước khi nó lên môi trường thật.

Ba trạng thái mọi lượt gọi đều có

Ba trạng thái này không phụ thuộc vào công nghệ, không phụ thuộc vào nhà cung cấp, và không có ngoại lệ. Nếu ticket của bạn chỉ mô tả trạng thái thành công thì bạn mới viết một phần ba màn hình.

Ví dụ theo cấp độ

Cơ bản — "Đang tải" rồi hiện danh sách, đó là một lượt hỏi và một lượt trả

Tình huống: bạn mở màn hình lịch sử đơn hàng. Trong khoảng nửa giây đầu màn hình hiện "Đang tải", sau đó danh sách đơn hiện ra.

Điều thật sự xảy ra: app gửi một request — "cho tôi 20 đơn gần nhất của người dùng 8842" — và chờ. Khi response về, app vẽ danh sách. Chữ "Đang tải" chính là khoảng giữa hai nửa đó.

Học được: mỗi khối dữ liệu bạn thấy trên màn hình là kết quả của ít nhất một lượt hỏi. Khi bạn thêm một khối mới vào thiết kế, bạn đang thêm một lượt hỏi — hoặc đang yêu cầu bên kia trả thêm dữ liệu trong lượt hỏi cũ. Cả hai đều là việc phải làm, không phải "chỉ thêm cái ô".

Trung bình — Spec ba trạng thái cho một màn hình lấy dữ liệu từ nhà cung cấp

Tình huống: màn hình chi tiết đơn hàng cần hiện trạng thái vận chuyển mới nhất, lấy trực tiếp từ hệ thống của đơn vị vận chuyển.

Việc cần viết ra trong ticket:

Học được: "chờ tối đa bao lâu" và "thất bại thì hiện gì" là quyết định sản phẩm, không phải quyết định kỹ thuật. Không viết ra thì lập trình viên vẫn phải chọn — chỉ là chọn thay bạn.

Nâng cao — Một màn hình gọi năm nơi, một nơi chậm 3 giây

Tình huống: trang chủ sau đăng nhập hiện năm khối, mỗi khối lấy dữ liệu từ một nơi khác nhau. Thời gian phản hồi đo được:

Ba cách thiết kế, ba kết quả khác hẳn nhau:

• Gọi lần lượt — chờ khối này xong mới gọi khối sau: 180 + 240 + 150 + 120 + 3.000 = 3.690 ms mới thấy gì đó. Tệ nhất, và là cách một thiết kế "tải xong hết rồi hiện" hay rơi vào.
• Gọi song song — bắn cả năm cùng lúc rồi chờ đủ: mất bằng khối chậm nhất, 3.000 ms. Tốt hơn nhưng người dùng vẫn nhìn màn hình trắng 3 giây chỉ vì một khối phụ.
• Gọi song song và tách khối chậm ra — vẽ ngay khi bốn khối nội bộ về (khối chậm nhất trong nhóm này là 240 ms), khối gợi ý hiện khung chờ riêng và tự điền vào sau khoảng 3 giây: màn hình dùng được sau 240 ms.

Quyết định bạn phải đưa ra, không phải lập trình viên: khối nào bắt buộc phải có trước khi màn hình được coi là dùng được, và khối nào được phép đến muộn. Với ví dụ này, gợi ý sản phẩm rõ ràng thuộc nhóm được phép đến muộn — và câu đó phải nằm trong ticket.

Và nếu khối gợi ý cũng thất bại? Trang vẫn phải dùng được. Một khối phụ hỏng không được kéo sập cả trang chủ — hãy viết thẳng câu đó vào tiêu chí nghiệm thu.

Áp dụng khi viết spec

Với mỗi màn hình có dữ liệu, ticket của bạn nên trả lời được bốn nhóm câu hỏi:

1. Nguồn. Mỗi mẩu dữ liệu đến từ đâu — đã có sẵn trong hệ thống, phải gọi nhà cung cấp, hay được tính ra từ dữ liệu khác? Lập một bảng ba cột và điền hết. Những ô bạn không điền được chính là những chỗ cần hỏi.
2. Ba trạng thái. Đang tải hiện gì, thành công hiện gì (kể cả khi rỗng), thất bại hiện gì và người dùng làm gì tiếp.
3. Thời gian. Chờ tối đa bao lâu thì coi là thất bại. Khối nào bắt buộc, khối nào được phép đến muộn.
4. Tần suất. Màn hình này gọi bao nhiêu lượt, mỗi bao lâu một lần? Một danh sách 20 dòng mà mỗi dòng tự gọi thêm một lượt để lấy trạng thái là 1 + 20 = 21 lượt gọi cho một màn hình — gần như luôn nên gộp thành một lượt duy nhất. Một màn hình tự làm mới mỗi 5 giây, với 200 người đang mở cùng lúc, là 40 lượt mỗi giây (200 × 12 lượt/phút = 2.400 lượt/phút) — hỏi xem con số đó có chấp nhận được không trước khi chốt thiết kế.

Câu hỏi nên hỏi dev

• "Dữ liệu của khối này mình đã có sẵn hay phải gọi ra ngoài?"
• "Lượt gọi này thường mất bao lâu, và lâu nhất là bao nhiêu?"
• "Nếu nó thất bại thì hiện tại màn hình đang xử lý thế nào?"
• "Response có sẵn trường này chưa, hay phải xin nhà cung cấp bổ sung?"
• "Màn hình này gọi bao nhiêu lượt? Có gộp lại thành một lượt được không?"
• "Bên kia có giới hạn số lượt gọi mỗi phút không, và chạm giới hạn thì chuyện gì xảy ra?"

Sai lầm thường gặp

• Thiết kế chỉ có trạng thái thành công. Đang tải và thất bại bị bỏ trắng, rồi người dùng gặp màn hình đứng im.
• Coi danh sách rỗng là lỗi, hiện thông báo lỗi cho một tài khoản mới hoàn toàn bình thường.
• Đưa vào thiết kế một trường mà nhà cung cấp không hề trả về — phát hiện ở khâu kiểm thử, sát ngày phát hành.
• Viết "tải nhanh" trong tiêu chí nghiệm thu thay vì một con số cụ thể.
• Để một khối phụ chậm hoặc hỏng kéo sập cả màn hình.
• Tự làm mới liên tục vì "cho nó cập nhật", không ai tính ra tổng số lượt gọi mỗi giây.

Definition of done — dấu hiệu bạn đã đạt

• Với bất kỳ màn hình nào trong khu vực của mình, bạn chỉ được vào từng khối và nói dữ liệu của nó đến từ đâu.
• Mọi ticket bạn viết cho màn hình có dữ liệu đều có đủ ba trạng thái, kèm câu chữ cụ thể cho trạng thái thất bại.
• Bạn đọc được tài liệu API của một nhà cung cấp và trả lời được: có trường mình cần không, gọi lúc nào, lỗi thì trả về gì.
• Bạn phát hiện được thiết kế gọi dữ liệu quá thường xuyên và nêu vấn đề trước khi nó lên môi trường thật.

Đi sâu hơn

• Webhook vs polling — khi dữ liệu đến với bạn thay vì bạn đi hỏi, và vì sao có thứ không bao giờ tức thời.
• Tích hợp bên thứ ba — sống chung với một hệ thống bạn không kiểm soát.
• Browser DevTools — nhìn tận mắt những request mà trang đang gửi đi.
• Caching — giảm số lượt gọi mà vẫn giữ dữ liệu đủ mới.

PM technical literacy spectrum

Không cần code, nhưng cần read code + spec integration. Litmus test: bạn đọc API doc Stripe và spec được flow checkout không?

Core concepts

• REST API — verb (GET, POST, PUT, DELETE), status code (2xx, 4xx, 5xx).
• JSON payload — request body, response body.
• Authentication — API key, OAuth, JWT.
• Webhook — server-to-server callback.
• Async vs sync — queue, retry, idempotency.
• Rate limit — quota, backoff.
• Pagination — cursor vs offset.
• GraphQL — alternative to REST, client-specified query.

Reading API doc — Stripe example

Stripe doc là gold standard. PM nên đọc và identify:

• Authentication method.
• Endpoint nào dùng cho use case của bạn.
• Required vs optional field.
• Error code và handling.
• Webhook event để listen.
• Test mode vs production.

Spec integration cho PRD

1. System diagram — who calls whom.
2. Sequence diagram — order of API call.
3. Data contract — schema input/output.
4. Error handling — retry policy, fallback UX.
5. Monitoring — what alert when fails.

Vietnam-specific integration

• VNPay, MoMo, ZaloPay payment API.
• VietQR transfer.
• eKYC API (FPT.AI, VinAI).
• Shipping API (GHN, GHTK, J&T).

Common pitfalls

• Spec dựa trên website screenshot mà không đọc API doc → reality khác.
• Bỏ qua webhook → poll inefficient.
• Không hiểu idempotency → duplicate charge.