Có bất kỳ nguyên tắc quy ước đặt tên nào cho các API REST không?

Question

Khi tạo API REST, có bất kỳ nguyên tắc hoặc tiêu chuẩn defacto nào cho quy ước đặt tên trong API (ví dụ: thành phần đường dẫn URL điểm cuối, tham số truy vấn) không? Thẻ lạc đà có phải là tiêu chuẩn hoặc dấu gạch dưới không? khác?

Ví dụ:

api.service.com/helloWorld/userId/x 

hoặc

api.service.com/hello_world/user_id/x 

Lưu ý: Đây không phải là một câu hỏi về thiết kế API RESTful, chứ không phải chủ trương quy ước đặt tên để sử dụng cho các thành phần con đường cuối cùng và/hoặc truy vấn tham số chuỗi được sử dụng.

Mọi nguyên tắc sẽ được đánh giá cao.

Answer 1

Tôi nghĩ bạn nên tránh mũ lạc đà.Định mức là sử dụng chữ thường. Tôi cũng muốn tránh dấu gạch dưới và dấu gạch ngang sử dụng thay vì

Vì vậy, URL của bạn sẽ giống như thế này (bỏ qua các vấn đề thiết kế như bạn yêu cầu :-))

api.service.com/hello-world/user-id/x 

Answer 2

Tôi không nghĩ rằng các trường hợp lạc đà là vấn đề trong ví dụ đó, nhưng tôi tưởng tượng một quy ước đặt tên RESTful hơn cho ví dụ trên sẽ là:

api.service.com/helloWorld/userId/x

thay vì sau đó làm cho userId một tham số truy vấn (hoàn toàn hợp pháp) ví dụ của tôi biểu thị tài nguyên đó trong, IMO, một cách RESTful hơn.

Answer 3

Tôi có thể nói rằng nên sử dụng càng ít ký tự đặc biệt càng tốt trong URL REST. Một trong những lợi ích của REST là nó làm cho "giao diện" cho một dịch vụ dễ đọc. Trường hợp lạc đà hoặc trường hợp Pascal có lẽ tốt cho tên tài nguyên (Người dùng hoặc người dùng). Tôi không nghĩ có bất kỳ tiêu chuẩn cứng nào xung quanh REST.

Ngoài ra, tôi nghĩ Gandalf là đúng, nó thường sạch hơn trong REST để không sử dụng tham số chuỗi truy vấn, nhưng thay vào đó tạo đường dẫn xác định tài nguyên nào bạn muốn xử lý.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc

Answer 4

Nhìn kỹ vào URI của tài nguyên web thông thường. Đó là mẫu của bạn. Hãy suy nghĩ về cây thư mục; sử dụng tên tệp và thư mục giống như Linux đơn giản.

HelloWorld không phải là một loại tài nguyên thực sự tốt. Nó không phải là một "điều". Nó có thể là, nhưng nó không phải là rất giống như danh từ. A greeting là một điều.

user-id có thể là danh từ mà bạn đang tìm nạp. Tuy nhiên, điều đáng ngờ là kết quả của yêu cầu của bạn chỉ là user_id. Có nhiều khả năng kết quả của yêu cầu là Người dùng. Do đó, user là danh từ bạn đang tìm nạp

www.example.com/greeting/user/x/ 

Tạo ý nghĩa với tôi. Tập trung vào việc thực hiện yêu cầu REST của bạn một loại cụm từ danh từ - một đường dẫn thông qua một hệ thống phân cấp (hoặc phân loại hoặc thư mục). Sử dụng danh từ đơn giản nhất có thể, tránh các cụm từ danh từ nếu có thể.

Nói chung, cụm từ danh từ kép thường có nghĩa là một bước khác trong cấu trúc phân cấp của bạn. Vì vậy, bạn không có /hello-world/user/ và /hello-universe/user/. Bạn có /hello/world/user/ và hello/universe/user/. Hoặc có thể là /world/hello/user/ và /universe/hello/user/.

Vấn đề là cung cấp đường dẫn điều hướng giữa các tài nguyên.

Answer 5

số REST của không có gì để làm với quy ước đặt tên URI . Nếu bạn bao gồm các quy ước này như một phần của API, ngoài băng, thay vì chỉ qua siêu văn bản, thì API của bạn không phải là RESTful.

Để biết thêm thông tin, xem http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Answer 6

Tên miền không phân nhạy cảm nhưng phần còn lại của URI chắc chắn có thể được. Đó là một sai lầm lớn để giả định URI không phân biệt chữ hoa chữ thường.

Answer 7

API REST cho Dropbox, Twitter, Google Web Services và Facebook tất cả dấu gạch dưới sử dụng.

Answer 8

'UserId' hoàn toàn là phương pháp sai. Phương pháp động từ (phương pháp HTTP) và danh từ là những gì Roy Fielding có nghĩa là cho The REST architecture. Các danh từ là một trong hai:

1. Một Collection thứ
2. Một điều

Một quy ước đặt tên tốt là:

[POST or Create](To the *collection*) 
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing) 
sub.domain.tld/class_name/id_value.{media_type} 

[PUT or Update](of *one* thing) 
sub.domain.tld/class_name/id_value.{media_type} 

[DELETE](of *one* thing) 
sub.domain.tld/class_name/id_value.{media_type} 

[GET or Search](of a *collection*, FRIENDLY URL) 
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs} 

[GET or Search](of a *collection*, Normal URL) 
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs 

đâu {MEDIA_TYPE} là một trong những : json, xml, rss, pdf, png, thậm chí html.

Có thể phân biệt các bộ sưu tập bằng cách thêm một 's' ở cuối, như:

'users.json' *collection of things* 
'user/id_value.json' *single thing* 

Nhưng điều này có nghĩa là bạn phải theo dõi về nơi bạn đã đặt 's' và nơi bạn không. Cộng với một nửa hành tinh (người châu Á cho người mới bắt đầu) nói ngôn ngữ không có số nhiều rõ ràng để URL ít thân thiện hơn với chúng.

Answer 9

Tôi có danh sách các nguyên tắc tại http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html mà chúng tôi đã sử dụng trong sản phẩm. Hướng dẫn luôn luôn gây tranh cãi ... Tôi nghĩ sự nhất quán đôi khi quan trọng hơn là làm mọi thứ hoàn hảo (nếu có một thứ như vậy).

Answer 10

Nếu bạn xác thực khách hàng của bạn với OAuth2 Tôi nghĩ rằng bạn sẽ cần phải nhấn mạnh trong ít nhất hai tên tham số của bạn:

• client_id
• client_secret

Tôi đã sử dụng camelCase trong tôi (chưa được xuất bản) REST API. Trong khi viết tài liệu API tôi đã nghĩ đến việc thay đổi mọi thứ thành snake_case vì vậy tôi không phải giải thích tại sao các tham số Oauth là snake_case trong khi các tham số khác thì không.

Xem: https://tools.ietf.org/html/rfc6749