Self-documenting: nhìn vào đường dẫn của API là chúng ta có thể đoán dược mục đích sử dụng của nó.
Flexible: Tính mở rộng của API.
Unified structure and attribute names: Thống nhất về mặt cấu trúc cho resource cũng như cách đặt tên các thuộc tính.
Clear error message: Khi hệ thống xảy ra lỗi thì phải có hiển thị thông điệp rõ ràng để tiện cho việc fix bug.

Các nguyên tắc thiết kế API cần tuân thủ

Authorization

Tất cả API cần có rate limit. Đặc biệt là các API public.
Các API cần xác thực → Cần chú ý quyền sở hữu data trước khi cho phép thao tác (Đặc biệt là các thao tác chỉnh sửa/xóa dữ liệu)

HTTP Method

Sử dụng đúng method cho đúng mục đích của API
POST, GET, PUT, DELETE tương ứng với (Create, Read, Update, Delete)

Quy ước đặt tên, 1 số logic cơ bản

Sử dụng danh từ số nhiều và không dùng động từ
Sử dụng chữ thường trong URIs.
Thống nhất 1 loại convention đặt tên attribute trả về theo quy ước: tên_biến. VD: user_id, created_at…
Sử dụng ‘-‘ để dễ đọc các URIs, không dùng ‘_’ VD:

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable

http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //More error prone

Đối với các API get list data: bắt buộc có limit, offset (Có thể dùng page=xxx). Nếu không gửi lên thì nhận giá trị default ở phía backend.

Dữ liệu trả về

Cần định dạng dữ liệu trả về và nhất quán trong 1 project
Lựa chọn field trả về. Chỉ trả về dữ liệu Frontend thực sự cần. Không trả về dư thừa dữ liệu

HTTP status code và error message

Hiểu đúng về HTTP status code

200 OK — This is most commonly used HTTP code to show that the operation performed is successful.
201 CREATED — This can be used when you use POST method to create a new resource.
202 ACCEPTED — This can be used to acknowledge the request sent to the server.
400 BAD REQUEST — This can be used when client side input validation fails.
401 UNAUTHORIZED / 403 FORBIDDEN — This can be used if the user or the system is not authorised to perform certain operation.
404 NOT FOUND — This can be used if you are looking for certain resource and it is not available in the system.
500 INTERNAL SERVER ERROR — This should never be thrown explicitly but might occur if the system fails.
502 BAD GATEWAY — This can be used if server received an invalid response from the upstream server.

Error message:

Đối với error message trả về khi có lỗi xảy ra cần đảm báo dễ hiểu cho cả user, client developer và backend developer. Về cơ bản chúng ta sẽ có 3 message trả về phục vụ cho 3 đối tượng khác nhau:

user message (message trả về cho user)
internal message (message trả vể cho backend developer)
code (message trả về cho client developer)

Một message đầy đủ yêu cầu sẽ có dạng như sau:

{
    "error":{
        "userMessage": "Sorry, the requested resource does not exist",
        "internalMessage": "No car found in the database",
        "code":34
    }
}

Versioning

Versioning là một điều bắt buộc với tất cả resource, việc đánh version cho resource tuân thủ 2 nguyên tắc sau:

Bắt đầu bằng “v” và kết thúc bằng một số nguyên dương , tránh dùng số thập phân (dùng v1 thay vì v1.5)
Versioning sẽ được đặt ở vị trí đầu tiên của resource

Ví dụ:

GET /v1/users/1 thay vì GET /users/v1.5/1

Share on Facebook

Kinhnghiemlaptrinh.com

Những yếu tố quyết định chất lượng API tốt