Một supplier mới đến dưới dạng một file PDF, một bộ credential và một URL sandbox. Cám dỗ là mở tài liệu ra ở endpoint đầu tiên rồi gõ luôn, vì endpoint đầu tiên bao giờ cũng là search mà search thì trông dễ. Mình bỏ thói quen đó rồi. Lượt đầu là đọc, theo một danh sách câu hỏi cố định — không câu nào được trả lời bởi danh sách endpoint, và câu nào cũng quyết định hình dạng cái module mình sắp viết.
Auth, và một credential xoay vòng thế nào
Credential đó là cái gì: một key tĩnh, một lần login trả về token có thời hạn, hay một chữ ký tính theo từng request. Rồi hỏi cái mà tài liệu gần như không bao giờ trả lời. Nó xoay vòng ra sao — ai cấp cái mới, cái cũ có còn dùng được trong lúc cái mới đã sống chưa, và mình đổi được nó mà không cần deploy không? Một credential xoay vòng mà không có khoảng gối đầu là một sự cố đã được người khác đặt lịch sẵn, vào một ngày không ai báo mình. Biết điều đó từ ngày đầu nghĩa là nó nằm trong config ngay từ commit đầu tiên.
Search một nhịp hay một nhịp rồi chờ
Supplier trả lời ngay trên cùng một kết nối, hay đưa lại một token và bắt mình poll? Câu này quyết định module thuộc mô hình thực thi nào — nền tảng chạy cả mô hình bất đồng bộ lẫn đồng bộ sau cùng một public contract — và quyết định độ trễ của supplier rơi vào đâu: nằm trong một cú gọi thì nó tranh chỗ với một cái deadline search cứng, còn trải ra thành nhiều lượt poll thì thành câu hỏi poll bao nhiêu lần là đáng.
Một offer là gì, và nó sống được bao lâu
Thứ khách chọn phải có một định danh, và mình cần ba điều về nó: nó gồm những gì, chạy lại đúng lượt search đó thì nó có giữ nguyên không, và supplier còn nhận ra nó trong bao lâu. Có loại token mờ đục và ngắn hạn, có loại có cấu trúc và gần như vĩnh viễn, có loại chẳng thuộc bên nào mà tài liệu thì không nói. Chỗ này quan trọng hơn ở phần lớn nơi khác, vì state giữa các lần gọi nằm ngay trong một offer ID tổ hợp có version, decode ở bước prebook chứ không có session phía server — câu trả lời quyết định cái gì phải nhét vào ID và cái gì tính lại được sau.
Book có idempotent không, không thì tra bằng gì
Supplier có nhận một reference của mình rồi từ chối làm lần thứ hai trên nó không? Nếu có, câu chuyện khó nhất của cả tích hợp — cú timeout rơi đúng lúc tiền đang bay — coi như viết xong gần hết.
Nếu không, câu hỏi tiếp theo mới là câu quan trọng: có cách tra nào? Mình tìm được booking của họ bằng reference của mình, bằng ngày, bằng tên khách — bằng bất cứ thứ gì mình còn giữ sau một cú timeout — hay không? Không idempotent mà cũng không có cách tra nghĩa là mọi ca booking mập mờ đều phải có người ngồi đối soát, và điều đó thuộc về phần ước lượng, chứ không phải thuộc về một bất ngờ ba tuần sau.
Lỗi nằm ở đâu, và lỗi nào là của mình
Có supplier trả HTTP 200 kèm một thất bại trong body, chuyện đó đủ nổi tiếng rồi. Câu hỏi tinh hơn: có mã lỗi ổn định đọc được bằng máy không, hay thứ duy nhất phân biệt được là một câu chữ mà quý sau sẽ có người viết lại? Và lỗi nào nghĩa là retry, lỗi nào nghĩa là dừng, lỗi nào nghĩa là dừng và gọi người?
Chính sách có cấu trúc không
Một chính sách huỷ ở dạng mốc thời gian cộng số tiền thì lọc được, so sánh được, xử lý tự động được. Cũng chính sách đó ở dạng một đoạn văn xuôi thì chỉ hiển thị được. Một câu trả lời đó quyết định cả một nhóm tính năng có làm được trên supplier này hay không, và không mẹo nào ở phía sau dựng lại được cái cấu trúc chưa bao giờ được gửi sang.
Mô hình rate ngụ ý điều gì
Rồi tới câu hỏi đứng sau nhánh rẽ lớn nhất: một token đặt được N phòng, hay giá từng phòng độc lập với nhau? Nền tảng ghi hẳn hai pattern offer thành tài liệu vì các supplier khác nhau thật ở chỗ này — A trả về một token duy nhất đặt N phòng; B tính giá từng phòng riêng, và danh sách offer là cái ma trận tổ hợp hợp lệ được materialise ra. Đọc sai chỗ này không lỗi ầm ĩ. Nó lỗi thành một booking hai phòng mà phòng thứ hai lặng lẽ ăn giá của phòng thứ nhất, phát hiện ra ở một tờ hoá đơn. Mọi tích hợp đều phải khai mình thuộc pattern nào, và đoạn này trong tài liệu chính là chỗ lời khai đó đi ra.
Giới hạn, và những gì sandbox không nói cho mình biết
Rate limit, trần concurrency, số khách tối đa mỗi request, ngày được đặt xa tới đâu. Rồi tới nửa hữu ích hơn: liệt kê những gì sandbox không cho mình thấy. Nó thường là một bộ dữ liệu nhỏ cố định, giới hạn rộng rãi và không bao giờ hỏng — không có throttling, không có độ trễ thật, không có cái đa dạng của chính sách huỷ ngoài đời, không có những lỗi chỉ tồn tại vì hàng thật bán hết. Tất cả bọn đó tới vào đúng ngày đầu tiên có traffic thật.
Rồi mới đọc: catalogue lỗi trước, đường đẹp sau
Khi bắt đầu đọc từng endpoint, mình đọc catalogue lỗi trước. Đường đẹp dài đúng một đoạn và gần như làm đúng do vô tình. Danh sách lỗi mới là chỗ lộ ra mô hình thế giới thật của supplier: họ tin có những trạng thái nào, họ chịu phân biệt những trạng thái nào, và họ cho rằng cái gì là lỗi của mình. Nếu tài liệu không có catalogue lỗi nào cả, thì đó là điều hữu ích nhất đọc được tới lúc này, và nó đi thẳng vào phần ước lượng.
Bắt lấy cú gọi thật đầu tiên, rồi ghi bảng mapping lại
Lần đầu credential chạy được, lưu nguyên cả cuộc trao đổi, không sửa gì. Tài liệu nói supplier định làm gì; bản ghi nói họ làm gì, và chỗ nào hai bên lệch nhau thì bản ghi thắng.
Rồi ghi bảng mapping field vào chỗ người sau sẽ tìm thấy: field của họ, field của mình, phép biến đổi, và cái ca đã thuyết phục mình. Cột cuối là cột tự trả tiền cho nó — một năm nữa bảng mapping trông sẽ rất tuỳ tiện, và chỉ dòng ghi chú đó giải thích được vì sao nó không tuỳ tiện.
Con số ước lượng đi ra từ lượt đọc
Đếm endpoint là cách ước lượng việc tích hợp của người chưa đọc tài liệu. Hai supplier có thể cùng có sáu endpoint. Một bên là JSON đồng bộ, idempotent theo reference của mình, chính sách có cấu trúc, pattern A — vài ngày. Bên kia phải poll để lấy kết quả, không idempotent và không tra được theo reference của mình, tính giá từng phòng độc lập và viết chính sách bằng văn xuôi — cái đó là nhiều tuần, và mấy tuần đó nằm ở phần đối soát chứ không nằm ở HTTP.
Mình chưa từng đem các câu trả lời này đối chiếu với thời gian thật mà từng cái trong khoảng chín mươi tích hợp đã tốn, nên không có bảng nào để đăng. Cái mình nói được là: mọi con số mình từng ước lượng dựa trên số endpoint đều sai theo cùng một chiều.