Yêu cầu đầu tiên tới một API xa lạ hầu như luôn được viết theo kiểu thử và sửa: sai header, gõ nhầm tham số, thừa một dấu cách trong khóa. Trên môi trường thật, mỗi lỗi như vậy đều phải trả giá bằng một khoản bị trừ tiền hoặc một số điện thoại bị hỏng. Môi trường thử nghiệm sinh ra để toàn bộ quá trình mò mẫm đó diễn ra mà không mất chi phí. Dưới đây là thứ tự kiểm tra tích hợp, những yêu cầu nào miễn phí và những lỗi nào thường làm hỏng ngày làm việc đầu tiên với API.
Vì sao cần môi trường thử nghiệm trước khi gọi API thật
Hiếm khi tích hợp xong ngay từ lần đầu, và nguyên nhân không nằm ở trình độ lập trình viên: trong một hệ thống lạ luôn có những chi tiết chỉ thấy được khi làm thực tế, như định dạng ngày trong phản hồi, chữ hoa chữ thường của tham số, thứ tự các đối số. Môi trường thử nghiệm cho bạn quyền được sai: một yêu cầu sai ở đó chỉ trả về mã lỗi, không trừ số dư và không chiếm dụng tài nguyên cần cho tác vụ thật.
Một lý do khác là niềm tin vào định dạng phản hồi. Chừng nào lập trình viên chưa tận mắt thấy phản hồi thực của máy chủ, gồm cấu trúc lồng nhau của các trường, kiểu dữ liệu, cách biểu thị lỗi, thì mã viết chỉ dựa vào tài liệu vẫn chỉ là giả định. Một yêu cầu thử biến giả định thành sự thật đã được kiểm chứng, trước khi quy trình thật bắt đầu phụ thuộc vào nó.
Thứ tự các bước tích hợp đầu tiên
Một trình tự hợp lý sẽ không bỏ qua các mức độ phức tạp. Bước đầu tiên là lấy khóa truy cập và chắc chắn rằng khóa tồn tại và đang hoạt động: chỉ cần vậy là đủ để phân biệt vấn đề nằm ở chính khóa hay ở logic của yêu cầu trong các bước sau. Bước thứ hai là một yêu cầu đơn giản, không mang nội dung nghiệp vụ, chỉ kiểm tra xác thực: gọi một phương thức tra cứu không đòi hỏi chọn quốc gia, dịch vụ hay số tiền. Phản hồi thành công nghĩa là khóa và header đã được cấu hình đúng, và bạn có thể chuyển sang xử lý nội dung thay vì loay hoay với quyền truy cập.
Bước thứ ba là xem định dạng phản hồi thực tế: những trường nào được trả về, mỗi mã trạng thái có ý nghĩa gì, phản hồi lỗi trông như thế nào. Bước này thường bị bỏ qua vì người ta tin vào tài liệu, nhưng làm vậy là không nên — phản hồi thực đôi khi khác với ví dụ ở những chi tiết quan trọng đúng với logic xử lý của bạn. Chỉ sau khi đã đi hết cả ba bước mới nên chuyển sang các phương thức tốn tiền hoặc chiếm dụng tài nguyên: yêu cầu số, mua kích hoạt, đặt trước kênh. Chuyển sang phương thức tính phí quá sớm sẽ biến việc gỡ lỗi tích hợp thành gỡ lỗi bằng tiền của chính bạn.
Yêu cầu nào miễn phí, yêu cầu nào bị trừ tiền
Các phương thức tra cứu, như danh sách quốc gia, danh sách dịch vụ, giá hiện tại theo từng hướng, thường miễn phí và không giới hạn số lần gọi trong mức hợp lý: đó là bảng hàng hóa chứ không phải hành động. Kiểm tra trạng thái của một lượt kích hoạt đã tạo và kiểm tra số dư thường cũng không tốn gì, vì chúng chỉ đọc trạng thái chứ không thay đổi nó. Việc trừ tiền xảy ra ở những chỗ hệ thống giữ tài nguyên cho bạn: yêu cầu số, bắt đầu kích hoạt, gia hạn thuê, mua kênh — tiền bị trừ khỏi số dư dù bạn có nhận được kết quả cần thiết hay không. Hãy đối chiếu ranh giới giữa miễn phí và có phí với tài liệu API trước lần gọi thật đầu tiên, thay vì tìm ra nó qua những lần bị trừ tiền ngẫu nhiên.
Những lỗi điển hình của ngày đầu tiên
Lỗi phổ biến và tốn kém nhất là khóa thật vô tình nằm trong môi trường thử: lập trình viên sao chép ví dụ từ tài liệu, thay khóa của mình mà không nhìn kỹ, và ngay lần chạy thử đầu tiên đã trừ tiền từ số dư thật. Việc tách khóa giữa các môi trường và hậu quả của nó được phân tích trong bài dữ liệu cho kiểm thử: cách không đưa tài khoản thật vào môi trường thử.
Lỗi thứ hai là yêu cầu số lặp lại trong vòng lặp mà không có độ trễ: nếu mã không đến ngay, một đoạn script có logic thiếu cân nhắc sẽ yêu cầu số mới ngay lập tức, thay vì chờ một khoảng nghỉ và chỉ thử số lần hợp lý. Mỗi lần thử trên một hướng kém đều bị tính phí lại, và chi phí cho một kết quả tăng lên gấp nhiều lần so với chi phí của một lần thử — vấn đề này được phân tích trong bài về chi phí ẩn: hủy, thử lại và thời gian chết.
Lỗi thứ ba là không xử lý các trường hợp từ chối: mã chỉ viết cho luồng suôn sẻ sẽ không phân biệt được «mã chưa đến, hãy chờ» với «hướng này không khả dụng» hay «khóa bị khóa», nên hoặc treo mà không phản ứng, hoặc dồn dập gửi lại yêu cầu không có khoảng nghỉ. Xử lý từng loại từ chối bằng một nhánh logic riêng không phải là cải tiến tùy chọn, mà là điều kiện để một phản hồi lỗi không biến thành một đợt yêu cầu vô ích.
Cần ghi lại gì trước khi chuyển sang môi trường thật
Trước lần gọi thật đầu tiên, nên ghi lại bằng văn bản bốn điều: khóa nào thuộc môi trường thử và khóa nào thuộc môi trường thật, và hai loại khóa này không được trùng nhau về mặt vật lý; phương thức nào có phí và phương thức nào không — dựa trên kết quả tự kiểm tra của bạn chứ không dựa vào trí nhớ; khoảng nghỉ hợp lý và số lần thử lại giữa các lần thất bại, thay vì một vòng lặp vô hạn; và hạn mức chi tiêu cho khóa phòng trường hợp logic thử lại ở đâu đó bị sai. Cách đặt ngưỡng theo ngày và theo tháng cho khóa được mô tả trong bài hạn mức cho nhóm: cách giới hạn chi tiêu.
Câu hỏi thường gặp
Có thể kiểm thử toàn bộ kịch bản mà không tốn một đồng nào không?
Kiểm tra khóa, xác thực và định dạng phản hồi thì có, hoàn toàn miễn phí. Việc nhận số hoặc bắt đầu kích hoạt sẽ cần ít nhất một lần gọi có phí, nhưng chỉ nên làm bước này sau khi mọi thứ còn lại đã được kiểm tra.
Làm sao nhanh chóng nhận ra khóa bị đặt nhầm môi trường?
Thực hiện một yêu cầu miễn phí thật đơn giản và so sánh số dư trước và sau: nếu số dư thay đổi ở một bước miễn phí, nghĩa là khóa đang trỏ không đúng nơi bạn mong đợi, và nên dừng ngay các lần gọi tiếp theo.
Nên lặp lại yêu cầu bao nhiêu lần nếu mã không đến?
Mốc tham khảo hợp lý là một lần thử lại sau khoảng nghỉ, chứ không phải một vòng lặp vô tận ngay sau lần hết thời gian chờ đầu tiên: lần thử thứ hai giúp loại trừ độ trễ ngẫu nhiên, còn thất bại mang tính hệ thống trên một hướng nghĩa là vấn đề nằm ở hướng đó chứ không phải do vận may.
Sơ đồ đầy đủ về các phương thức, mã phản hồi và giới hạn nằm trong phần tài liệu API trên turbon.rent: ở đó cũng ghi rõ lệnh gọi nào miễn phí và lệnh gọi nào trừ tiền từ số dư.