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để  thể  tả một API cho đồng nghiệpđối tác hiểu  sử dụng lại được thì cũng  một bài toán thú vị. Trong bài viết nàymình sẽ đưa ra một mẫu  tả tài liệu API  mình đã áp dụng trong dự án mình đang làm  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 \
-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”
} ‘

Published by Nguyen Quoc Dung

"If you only do what you can do You never be more than you are now"

Leave a comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: