Mẫu template mô tả hiệu quả cho một API

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 Correlation-Id
	Request Body	{ “name”: “Tran Van A”, “age”: 12, “grade”: “7A1” }
	Response Body	Success – Status code: 200 Error – Status code: 400 { “errorCode”: “037788”, “errorMessage”: “Duplicate name” }
CURL		curl -X POST \ https://192.168.0.0/student/create\ -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” } ‘

Advertisement