Quy chuẩn đặt tên trong thiết kế RESTful API

Khái quát về các loại Resource

Singleton and Collection Resources

Ví dụ, "Custommers" là Collection Resources, "Custommer" là Singleton Resources.
Đối với collection resource trên, chúng ta có thể xác định nó bằng URI " /customers". Còn đối với singleton resource, chúng ta sử dụng /customers/{customerId}.

Collection and Sub-collection Resources

Một Resource cũng có thể chứa nhiều các tập hợp khác (sub-collection). Ví dụ một chủ thể customer nắm giữ thông tin của các tài khoản accounts khác nhau. Chúng ta có thể định danh API này bằng URN: /customers/{customerId}/accounts để lấy toàn bộ thông tin sub-collection tài khoản của 1 user bất kì. Tương tự nếu muốn lấy 1 singleton resource account của accounts : /customers/{customerId}/accounts/{accountId}

Một vài lời khuyên đặt tên cho URI

Sử dụng danh từ để đại diện cho Resource.

RESTful API nên liên quan tới resource là một danh từ chỉ đối tượng thay vì một động từ chỉ hành động vì danh từ thường có các thuộc tính (properties) mà đông từ không có, cũng giống như resource thì thường có các attributes đi kèm.
Đi sâu hơn về phần này, chúng ta sẽ chia các API ra thành 4 nhóm: document, collection, store và controller. Tuỳ vào mục đích sử dụng, chúng ta chia các api ra các nhóm để sử dụng convension sao cho phù hợp nhất.

a. Document
Là resource chỉ các đối tượng độc lập, hay 1 bản ghi trong database. Nó là 1 singleton resource bên trong collection resource. Sử dụng danh từ số ít hoặc định danh của resource cho loại này.

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

b. Collection
Là các resource được quản lý bởi server. Client có thể yêu cầu thêm các resource mới vào collection. Tuy nhiên, việc có được thêm hay không lại phụ thuộc vào bên thứ 3 (admin hoặc chính collection đó quy định).

Sử dụng các tên số nhiều với type này.

http://api.example.com/api/device-management/managed-devices
http://api.example.com/api/user-management/users
http://api.example.com/api/user-management/users/{id}/accounts

c. Store
Là các resource được quản lý bởi client - tức là người sử dụng API đó. Client có toàn quyền CRUD với resource này. Loại resource này chỉ nên có 1 URI, và không nên tạo ra các URI khác.

Với các type này, chúng ta sử dụng các tên số nhiều.

http://api.example.com/api/song-management/users/{id}/playlists

d. Controller
Loại resoure này như đại diện cho 1 hành động, 1 quá trình và có input-output, hoặc 1 giá trị.

Với các type này, hơi đặc biệt 1 chút. chúng ta nên sử dụng động từ để dễ hình dung.

http://api.example.com/api/auth/login
http://api.example.com/api/send-mail

Nhất quán URI theo một chuẩn chung

Dưới đây là một số quy tắc chung được cộng đồng khuyên dùng:

a. Sử dụng "/" để ngăn cách quan hệ trong resource

http://api.example.com/api/song-management/users/{id}/playlists

b. Không sử dụng "/" cuối API

http://api.example.com/api/auth/login/ ->không nên
http://api.example.com/api/auth/login -> nên

c. Sử dụng "-"
Để tăng khả năng đọc liền mạch đối với các path dài. Ví dụ:

http://api.example.com/api/messenger-management/group-chat/{id}/download-archived-conversation -> nên
http://api.example.com/api/messengerManagement/groupChat/{id}/downloadArchivedConversation -> không nên

d. Không sử dụng "_"
Bạn cũng có thể sử dụng "_" thay cho "-" để ngăn cách các segment. Tuy nhiên với 1 số các ứng dụng sử dụng các custom font, dấu gạch dưới sẽ rất khó hoặc hoàn toàn không nhìn thấy. Để tăng khả năng đọc, chúng ta hãy thống nhất dùng "-" nhé.

http://api.example.com/api/messenger-management/group-chat/{id}/download-archived-conversation -> nên
http://api.example.com/api/messenger_management/group_chat/{id}/download_archived_conversation -> không nên

e. Sử dụng chữ cái thường
Do RFC 3986 quy định, trừ scheme và host, path của URI sẽ phải check các case liên quan đến chữ viết hoa và viết thường.

http://api.example.org/my-folder/my-doc  //1 -> giống với 2
HTTP://API.EXAMPLE.ORG/my-folder/my-doc  //2 -> giống với 1
http://api.example.org/My-Folder/my-doc  //3 -> khác 1 và 2 do path có chữ viết hoa

Vì vậy để thuận tiện, chúng ta nên sử dụng hoàn toàn chữ cái thường.

f. Không sử dụng định dạng file

Việc sử dụng định dạng file trên URI không có tác dụng gì và trông rất tệ. Nếu muốn truyền file, bạn nên giao tiếp qua API thông qua body của request với Content-Type header.

http://api.example.com/api/messenger-management/group-chat/{id}/download-archived-conversation -> nên
http://api.example.com/api/messenger-management/group-chat/{id}/download-archived-conversation.json -> không nên