Nếu như ai làm trong ngành phần mềm ngày nay thì chắc hẵn không còn lạ lẫm với việc dùng API cho công việc hằng ngày. Tuy nhiên, để có thể mô tả một API cho đồng nghiệp, đối tác hiểu và sử dụng lại được thì cũng là một bài toán thú vị. Trong bài viết này, mình sẽ đưa ra một mẫu mô tả tài liệu API mà mình đã áp dụng trong dự án mình đang làm và thấy hiệu quả cho các bạn để tham khảo. Theo mình một mô tả API hiệu quả thì nó phải đáp ứng được các tiêu chí sau: Dễ đọc, và dễ hiểu Có thể lấy sử dụng liền được Có thể dễ dàng cập nhật Do vậy những thành phần trong 1 mô tả sẽ gồm những phần sau: Một môt tả ngắn gọn về chức năng của API URI của API đó và ý nghĩa từng thành phần trong URI đó Method của API đó là gì API đó có header gì? Request body Response Sample cURL Ví dụ dưới đây là API cho việc tạo mới một học sinh vô trong danh sách học sinh của 1 trường Description Create new student Specification URI /create HTTP Method POST Required HTTP Headers Authorization Caller-Id Channel Content-Type …
Continue reading “Mẫu template mô tả hiệu quả cho một API”