1. Thuật ngữ

Tên	Mô tả
URL	Là đường dẫn tới resource
Resource	Là đối tượng hoặc một thứ gì đó có mang thông tin và có thể thao tác được trên đó. See more here.
Collection	Là một tập hợp các resource.

Show full post

2. Nguyên tắc thiết kế

Tất cả các API thiết kế theo chuẩn này có các nguyên tắc chung như sau:

Dựa trên khái niệm resource, end-point luôn là số nhiều (i.e. /resources)
Sử dụng HTTP Verb tương ứng với CRUD operation thay vì sử dụng tham số trên URL
1 end-point sẽ bao gồm các action cơ bản và chuẩn HTTP method tương ứng như sau:

Method	Description
GET /resources	Lấy tất cả resources, có paging nếu cần.
GET /resources?field=value	Lọc dựa trên trường thông tin của resource, có thể lọc dựa trên nhiều trường cùng lúc. Paging nếu cần. Bên ngoài các trường sẵn có, có thể thêm bộ lọc theo nghiệp vụ hoặc để đơn giản hoá.
GET /resources/{id}	Lấy 1 resource có id tương ứng.
POST /resources	Tạo mới 1 resource.
PUT /resources	Sửa 1 resource.
PATCH /resources	Sửa 1 phần của resource.
DELETE /resources	Xóa 1 resources.

3. Hạn chế sử dụng nested child resource

Mặc dù việc sử dụng nested end-point như:

GET /customers/:id/orders

được đề cập tới trong 1 số guideline của REST, tuy nhiên các sử dụng này nên được hạn chế vì các lý do sau:

Tạo ra end-point thừa

Thông thường nhu cầu query resource con không phụ thuộc vào resource cha vẫn sẽ nảy sinh, ví dụ tìm lệnh đã bị huỷ:

GET /customers/:id/orders?status=CANCEL   # multiple requests???
GET /orders?status=CANCEl   # much better

Như vậy trong hệ thống để query order sẽ có 2 end-point tuỳ tình huống sử dụng.

Không thân thiện UI trong trường hợp query nhiều resource con cùng lúc

Khi cần hiển thị vd số tài sản của nhiều KH cùng lúc nếu dùng nested sẽ phải query nhiều lần:

GET /accounts/0001666888/assets
GET /accounts/0001888666/assets   # tài khoản bự mua sẵn số TK đẹp và có nhiều sub-account

Thay vì vậy có thể chỉ cần query 1 lần:

GET /assets?accountId=0001666888,0001888666

4. API endpoint

URL nên chứa ít nhất một resource (để danh từ số nhiều). Ví dụ:

GET path: /users/10
DELETE path: /users/10

5. HTTP method (verbs)

Định nghĩa một tập các action có thể thao tác trên resource (GET, PUT, POST, DELETE)

(Nếu url là một câu thì resouce là danh từ HTTP method là động từ)

GET yêu cầu lấy thông tin resource và không nên có bất kỳ tác động làm thay đổi nào tới resouce
POST yêu cầu server tạo mới resouce (POST is non-idempotent, which mean that multiple request will have different effects)
PUT yêu cầu update resource (PUT is idempotent, which mean that multiple request will have the same effects)
DELETE yêu cầu xoá thông tin resource

6. HTTP response status codes

Khi client tạo request lên server qua api, client mong muốn hiểu được phản hồi từ server trả về, dù thành công, không thành công hoặc yêu cầu sai. Server nên trả về đúng status code.

7. HTTP codes

2xx (Success category): Status code chỉ ra rằng yêu cầu đã được nhận và xử lý thành công bởi server.
3xx (Redirection category)
4xx (Client error category): status code chỉ ra rằng client tạo yêu cầu ko đúng
5xx (Server error category)
See more

8. Field name casing convention

Cần đảm bảo tính nhất quán, request và response theo kiểu json thì các field cần camelCase.

9. Searching, filtering, sorting and pagination

Sorting khi client muốn sort một danh sách kết quả được trả ra

GET /companies?sort=rank_asc

Filtering lọc theo một số tiêu chí mà client muốn thông qua query params

GET /companies?category=bank&location=hanoi

Searching

GET /companies?search=BIDV tìm theo tên

Pagination

GET /companies?page = 2 list danh sách công ty ở trang thứ 2

10. Versioning

Việc nâng cấp api có thể sẽ làm break những ứng dụng đã dùng api do đó cần versioning api. Ví dụ:

http://domain.com/v1/users/…

11. Tham khảo

Tham khảo thêm bài viết chi tiết sau:

Thiết kế restful apis

#best-practices