Các tiêu chí cần có của mỗi api trong api docmentation

Bài đăng này đã không được cập nhật trong 3 năm

Giao diện lập trình ứng dụng, còn gọi là API (Application Programming Interface) là chương trình cho phép người dùng sử dụng các phương thức của một ứng dụng từ bên ngoài ứng dụng đó.

API không có bất kì một giao diện người dùng nào. Do đó, chúng ta cần tạo ra api documentation để bên thứ 3 có thể dễ dàng sử dụng API. Nói cách khác, api documentation là tài liệu quan trọng để giao tiếp giữa 2 bên client và server.

Khi phải bắt đầu viết api documentation , mình đã rất lúng túng vì không có một bản mẫu cũng như một chuẩn mực nhất định. Vì thế , mình đã tìm kiếm trên google, cũng như trao đổi thêm với team client ở project của mình để đưa ra các tiêu chí cần có với mỗi api khi viết vào api documentation.

1. Title (Api name)

Tên của api đó, nên ngắn gọn, dễ hiểu

Ví dụ: Show all user

2. URL

Cấu trúc của url( không cần viết cả root url)

Ví dụ: /api/users hoặc là /api/users/:id

3. Method

The request type

GET | POST | DELETE | PUT

4. Params

Danh sách các params (HEAD, POST, URL_Params)

ví dụ:

5. Success Response

Ví dụ:

Code: 200

Content: { id : 12 }

6. Error Response

Ví dụ:

Code: 401 UNAUTHORIZED

Content: { error : "Log in" }

Code: 422 Unprocessable Entry

Content: { error : "Email invalid" }

7. Notes

Đây là nơi ghi các bình luận , đánh giá , các chú ý đối với api.

Trên đây là các tiêu chí cần có trong mỗi api documentation mà mình thấy là cần thiết. Mong mọi người cùng đánh giá và bình luận thêm cách viết một api documentation để có được cách viết hợp lý nhất.