Designing Web APIs: đọc API của khách bằng con mắt người đã thiết kế ra nó

Mục lục 11 chương của Designing Web APIs đi từ câu hỏi “What’s an API?” qua bảo mật và best practice thiết kế, rồi rẽ sang Scaling APIs ở chương 6, sau đó là quản lý thay đổi (managing change) và developer programs. Như vậy một phần đáng kể của cuốn sách nói về những gì xảy ra sau khi API đã có người dùng thật.

Với một Forward Deployed Engineer, đó lại là phần đáng tiền nhất. Bạn hiếm khi được thiết kế API từ con số không. Việc thường gặp hơn nhiều là ngồi trước API của khách, vốn đã qua ba đời đội ngũ, và phải nối hệ thống của mình vào đó trước hạn demo.

Cuốn sách được viết cho phía bên kia: người xây và vận hành API. Đọc nó từ phía người tích hợp sẽ giúp bạn hiểu vì sao API của khách lại có hình dạng như hiện tại, và đoán trước được chỗ nào sẽ gãy.

Cuốn sách này là gì?

Tên đầy đủ là Designing Web APIs: Building APIs That Developers Love, do Brenda Jin, Saurabh Sahni và Amir Shevat viết, O’Reilly Media xuất bản năm 2018. Bản bìa mềm (ISBN 9781492026921) dài 232 trang; một số thư viện ghi số trang khác tùy ấn bản. Sách nhắm tới developer, kiến trúc sư và tech lead.

Phần giới thiệu sách thừa nhận rằng xây một API được nhiều người dùng, kèm một hệ sinh thái developer phát triển mạnh, là việc rất khó. Sách có bài tập thực hành để dựng API và vận hành nó trong production, cùng worksheet, checklist và case study từ Slack, Stripe, Facebook, Microsoft, Cloudinary, Oracle và GitHub. Phụ lục A mang tên API Design Worksheets.

Sách ra năm 2018, nên hãy coi nó là sách dạy tư duy chứ đừng xem như tài liệu tham khảo về công cụ. Cách đặt câu hỏi khi thiết kế API thay đổi chậm hơn nhiều so với công cụ.

Vì sao người tích hợp nên đọc sách của người thiết kế?

Mỗi API bạn gặp ở site khách là dấu vết của một chuỗi quyết định. Ai đó từng chọn một paradigm, chọn một cơ chế bảo mật, đặt ra giới hạn tải, rồi phải sửa API mà không làm gãy client cũ. Mục lục cuốn sách đi qua đúng từng chặng ấy: paradigm, bảo mật, scaling, quản lý thay đổi.

Khi đã biết người thiết kế phải cân nhắc những gì ở mỗi chặng, bạn đọc tài liệu API của khách theo cách khác. Bạn không còn chỉ hỏi endpoint nào trả dữ liệu gì. Bạn bắt đầu hỏi họ đã đánh đổi điều gì, và cái giá ấy sẽ rơi vào integration của bạn ở đâu.

Ba ý đáng mang theo tới site khách

Ý đầu tiên: paradigm giải thích hình dạng của API. Sách đặt chương API Paradigms ngay sau chương định nghĩa API, và một trong những mục tiêu sách nêu ra là phân biệt kiểu request-response với kiểu event-driven, gồm cả WebHooks và WebSockets.

Ở site khách, xác định đúng kiểu ngay từ đầu giúp bạn khỏi ép một mô hình quen tay lên hệ thống được xây theo logic khác.

Ý tiếp theo: scaling là con số bạn phải tính trước. Chương 6 có hẳn hai mục Paginating APIs và Rate-Limiting APIs. Thử hình dung khách cần đồng bộ 50.000 đơn hàng, API trả mỗi trang 100 bản ghi và cho phép 60 request mỗi phút: 500 request, khoảng 8 phút 20 giây cho một lần chạy đầy đủ.

Đó mới là trường hợp đẹp. Nếu 5% request lỗi và phải chạy lại, bạn có thêm 25 request, khoảng 25 giây nữa, và mỗi lần retry ăn vào chính hạn mức dành cho request mới. Giờ hãy tự đổi tham số và xem con số dịch chuyển ra sao:

Kịch bản giả định	Số request	Thời gian tối thiểu
Trang 100 bản ghi, 60 request/phút	500	8 phút 20 giây
Trang 1.000 bản ghi, 60 request/phút	50	50 giây
Trang 100 bản ghi, 10 request/phút	500	50 phút
Trang 100 bản ghi, 10 request/phút, 5% retry	525	52 phút 30 giây

Bài học nằm ở hàng thứ ba. Cùng một khối dữ liệu, chỉ cần hạn mức chặt hơn là lời hứa “gần thời gian thực” tan biến. Trang lớn hơn rút ngắn thời gian, nhưng mỗi response nặng hơn và một lần lỗi phải tải lại nhiều dữ liệu hơn. Bạn cần biết điều này trước buổi demo, không phải trong buổi demo.

Ý cuối cùng: mỗi lần API đổi phiên bản là một lần integration có thể gãy. Sách có một chương riêng về quản lý thay đổi, và phần bài tập của sách đi tới tận khâu vận hành API trong production. Với FDE, đọc lịch sử versioning và chính sách khai tử phiên bản cũ của khách nên là việc của tuần đầu tiên.

Những lỗi người tích hợp hay mắc

Lỗi phổ biến nhất là tính thời gian đồng bộ mà quên retry. Request lỗi vẫn bị trừ vào cùng một hạn mức, nên một job chạy lại vội vàng có thể tự đẩy mình vào vòng bị chặn, càng retry càng chậm.

Lỗi thứ hai là mặc định API nào cũng là REST. Nếu khách đẩy dữ liệu qua WebHooks hay WebSockets, kiến trúc của bạn phải nhận sự kiện chứ không đi hỏi định kỳ. Hỏi sai điều này thì cả lớp adapter phải viết lại.

Lỗi thứ ba là coi xác thực và phiên bản là việc làm một lần. Token hết hạn và phiên bản cũ bị khai tử thường gây sự cố vào đúng lúc không ai trực, vì thế hãy ghi rõ cả hai vào tài liệu vận hành ngay từ đầu.

Đọc theo thứ tự nào?

Không cần đọc tuyến tính. Hãy bắt đầu với API Paradigms và phần bảo mật, mang theo hai câu hỏi: API này thuộc kiểu gì, xác thực bằng gì và ai cấp quyền. Tiếp theo là Scaling APIs và chương quản lý thay đổi, nơi bạn tìm câu trả lời cho giới hạn request, kích thước trang và lịch khai tử phiên bản cũ.

Phụ lục A nên mở song song. Sách giới thiệu các worksheet như một mẫu cho quy trình thiết kế API; bạn có thể dùng chính mẫu ấy làm khung cho checklist discovery, chỉ đổi góc nhìn từ người thiết kế sang người hỏi.

Một bài tập để khép lại: chọn một API bạn sắp tích hợp, rồi dựa theo cách phụ lục A biến quy trình thiết kế thành mẫu, tự lập một trang gồm bốn ô là kiểu API, bảo mật, giới hạn tải và phiên bản.

Ở ô giới hạn tải, điền phép tính thời gian đồng bộ như bảng trên, có cả retry. Mang trang đó vào buổi discovery đầu tiên và đánh dấu ô nào khách chưa trả lời được.

Phần best practice thiết kế để sau, khi bạn cần đề xuất sửa API hoặc dựng lớp adapter. Phần developer programs dành cho lúc khách muốn mở API cho đối tác, hoặc khi bạn chuyển sang vai trò sát sản phẩm hơn.

Biến nó thành một dòng trong CV

Kỹ năng đọc API của người khác rất khó thấy nếu bạn chỉ ghi “tích hợp API”. Hãy ghi cụ thể bạn đã xử lý giới hạn request hay đợt nâng phiên bản nào, và kết quả ra sao, chẳng hạn job đồng bộ chạy trong bao lâu sau khi bạn tính lại kích thước trang.

Trong phỏng vấn, bốn câu hỏi về paradigm, bảo mật, giới hạn tải và phiên bản là khung tốt để kể lại một lần tích hợp khó: bạn đã hỏi gì, phát hiện gì, quyết định gì.

Developer giỏi thì đọc tài liệu API của khách. FDE giỏi đọc ra được những gì người viết tài liệu không ghi vào.