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 |
|
|
Request Body |
{
“name”: “Tran Van A”,
“age”: 12,
“grade”: “7A1”
}
|
|
Response Body |
|
|
CURL |
curl -X POST \
-H ‘Authorization: Bearer abc_xyz’\
-H ‘Caller-Id: Web’ \
-H ‘Channel: Web’ \
-H ‘Content-Type: application/json’ \
-H ‘Correlation-Id: abc_xyz’ \
-d ‘{
“name” : “Tran Van A”,
“age” : 12,
“grade” : “7A1”
} ‘
|