Postman và curl: kiểm tra API của khách trong ngày đầu, trước khi viết dòng code nào

Thử hình dung buổi sáng đầu tiên của bạn ở chỗ khách. Trước khi viết dòng code nào, bạn gõ một lệnh curl, gửi kèm token khách vừa cấp, để xem API của họ có thật sự trả về đúng những gì tài liệu mô tả hay không.

Hướng dẫn xây CRUD API bằng Node.js và Express trên blog của Harness khuyên dùng Postman để test endpoint bằng tay và Jest để test tự động, nhưng không nhắc tới curl. Với một tutorial thì điều đó hợp lý, vì API do chính bạn viết.

Ở chỗ khách thì ngược lại: API do người khác viết, có thể đã chạy nhiều năm, và tài liệu có thể đã lệch khỏi code thật.

Vì vậy, đừng coi việc kiểm tra API trong ngày đầu là thủ tục cho có. Khi chưa biết API thật sự trả về gì, mọi ước lượng về deployment đều chỉ là đoán.

curl trả lời câu hỏi “nó có sống không?”

Man page chính thức mô tả curl là công cụ truyền dữ liệu tới hoặc từ server thông qua URL. Mô tả ngắn gọn đó cũng giải thích vì sao nó hợp với buổi sáng đầu tiên: chỉ cần một terminal và một URL là bắt đầu được.

Cờ đầu tiên nên thuộc là -H (hoặc --header). Cờ này thêm một header vào request, chẳng hạn token xác thực. Thử hình dung khách là một công ty kho vận và đưa bạn endpoint tra cứu đơn hàng:

curl -H "Authorization: Bearer $TOKEN" https://api.khach-hang.vn/orders/123

Ba điều cần ghi lại ngay: request có thành công không, các trường trả về có khớp với tài liệu không, và khi bỏ header đi thì API báo lỗi ra sao. Bước cuối thường bị bỏ qua, nhưng nó cho bạn biết phần tích hợp bạn sắp viết sẽ phải xử lý lỗi xác thực ra sao.

Postman gọi việc này là API unit testing: xác nhận một endpoint trả đúng response cho một request cụ thể. curl làm tốt đúng một việc đó. Nhưng chỉ cần gọi tới request thứ năm, mỗi lần lại dán token bằng tay, bạn sẽ thấy nó bắt đầu bất tiện.

Postman giúp lưu lại và nối các request

Khi đã chắc API còn hoạt động, câu hỏi tiếp theo là các thao tác có ăn khớp với nhau không. Bài viết của Solène Lanchec trên blog Forest Admin ghép bốn thao tác CRUD với các HTTP method: PUT để cập nhật toàn bộ tài nguyên, PATCH để chỉ sửa một phần. API của khách không phải lúc nào cũng tuân theo quy ước này.

Bạn cần phát hiện điều đó trước khi viết code dựa trên nó.

Đây là việc của Postman. Hãy lập một collection cho tài nguyên đơn hàng gồm bốn thao tác create, read, update, delete. Mỗi thao tác thử ba trường hợp: request hợp lệ, request thiếu token, request có dữ liệu sai. Bốn nhân ba thành mười hai request, và chừng đó đã đủ để thấy API thật sự phản hồi ra sao ngay trong buổi sáng.

Theo Postman, Collection Runner nối các request thành một workflow. Bạn tạo đơn, đọc lại, PATCH đúng một trường, rồi đọc lại lần nữa. Nếu các trường khác bị xóa trắng sau lệnh PATCH, API của khách đang xử lý PATCH như PUT. Tốt nhất là biết chuyện này ngay hôm nay, khi thứ bị xóa mới chỉ là dữ liệu thử.

Ba lỗi hay gặp trong buổi đầu

Lỗi thứ nhất là thấy status 200 là yên tâm. Status thành công chưa nói gì về việc body có khớp tài liệu hay không: một response 200 vẫn có thể thiếu trường, đổi kiểu dữ liệu hoặc đặt tên khác tài liệu. Hãy đọc cả body, từng trường một.

Lỗi thứ hai là chỉ gọi API khi có token. Bạn sẽ biết đường thành công trông thế nào, nhưng không biết lỗi xác thực trả về ra sao. Đến khi token hết hạn trên production, code của bạn phải đoán.

Lỗi thứ ba là để collection nằm yên trong máy cá nhân sau buổi sáng đầu. Nó chỉ có giá trị khi được chạy lại, và khi người khác trong đội cũng chạy được.

Những gì cả hai công cụ không làm thay bạn

Hai công cụ này chỉ gửi request. Biết phải kiểm tra điều gì vẫn là việc của bạn. Hướng dẫn của Testsigma nêu contract testing là một loại API test riêng: xác minh API tuân theo spec đã định nghĩa. Nếu khách có spec, hãy so từng response với spec một cách có hệ thống.

Testsigma cũng khuyên kiểm tra định kỳ các lỗ hổng như SQL injection, XSS và broken authentication. Việc này cần một danh sách ca kiểm thử có chủ đích, gõ thêm vài request ngẫu nhiên thì không đủ. Request thiếu token trong collection ở trên chỉ là điểm bắt đầu, chưa phải một bài kiểm tra bảo mật.

Để collection không bị bỏ quên, Postman cho biết Newman hoặc Postman CLI có thể chạy collection và test trong pipeline CI/CD, còn Testsigma khuyên tự động hóa regression test cùng các luồng quan trọng. Mười hai request bạn viết hôm nay nên được chạy tự động mỗi khi phía khách deploy.

Postman còn quảng bá tài liệu tự sinh, luôn đồng bộ khi collection hoặc spec thay đổi. Với FDE, điểm này có giá trị thực tế: tài liệu sinh ra từ request bạn đã chạy thật là thứ đội của khách có thể dùng sau khi bạn rời dự án.

Nên học gì trước?

Học curl trước. Nó buộc bạn hiểu từng phần của một request: URL, method, header. Sau đó mới đến Postman, khi bạn đã biết mình muốn lưu và tự động hóa những gì. Song song với hai công cụ, hãy nắm chắc cách CRUD tương ứng với HTTP method, đặc biệt là khác biệt giữa PUT và PATCH.

Khi đọc JD cho vị trí FDE hoặc solutions engineer, hãy để ý các cụm như “integrate with customer APIs” hay “debug integrations”. Đó là những công việc diễn ra trong terminal và Postman. Trong CV, thay vì ghi “thành thạo Postman”, hãy viết về một collection cụ thể bạn đã dựng, ví dụ nó phát hiện API xử lý PATCH sai hoặc được đưa vào CI.

Ở chỗ khách, kết quả của ngày đầu chưa phải là code. Đó là một collection ghi lại API thật sự hoạt động thế nào, và nhờ nó, mọi dòng code về sau dựa trên hành vi đã được kiểm chứng.