Có bất kỳ hướng dẫn quy ước đặt tên nào cho API REST không? [đóng cửa]

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

Ví dụ:

api.service.com/helloWorld/userId/x

hoặc là

api.service.com/hello_world/user_id/x

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

Bất kỳ hướng dẫn sẽ được đánh giá cao.

Tôi nghĩ bạn nên tránh mũ lạc đà. Các tiêu chuẩn là sử dụng chữ in thường. Tôi cũng sẽ tránh dấu gạch dưới và sử dụng dấu gạch ngang thay thế

Vì vậy, URL của bạn sẽ trô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

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

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

HelloWorldkhông phải là một lớp tài nguyên thực sự tốt. Nó không có vẻ là một "điều". Nó có thể, nhưng nó không giống như danh từ. A greetinglà một điều.

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

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

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

Nói chung, cụm danh từ ghép thường có nghĩa là một bước khác trong hệ thống 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ể /world/hello/user/và /universe/hello/user/.

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

'UserId' hoàn toàn là cách tiếp cận sai. Cách tiếp cận Động từ (Phương thức HTTP) và Danh từ là ý nghĩa của Roy Fielding cho kiến trúc REST . Các danh từ là:

1. Một Bộ sưu tập 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

Trong đó {media_type} là một trong: json, xml, rss, pdf, png, thậm chí html.

Có thể phân biệt 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 nơi bạn đã đặt 's' và nơi bạn chưa có. 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 các ngôn ngữ mà không có số nhiều rõ ràng nên URL không thân thiện với họ.

Không. REST không liên quan gì đến các 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 tần, thay vì chỉ thông 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, hãy xem http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Tên miền không phân biệt chữ hoa chữ thường nhưng phần còn lại của URI chắc chắn có thể. Đó là một sai lầm lớn khi cho rằng URI không phân biệt chữ hoa chữ thường.

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

Tôi không nghĩ 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 đó biến userId thành 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.

Nếu bạn xác thực ứng dụng khách của mình bằng Oauth2, tôi nghĩ bạn sẽ cần gạch dưới cho ít nhất hai tên tham số của mình:

• khách hàng
• khách hàng

Tôi đã sử dụng camelCase trong API REST (chưa được công bố) của mình. 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 thông số Oauth lại là sn_case trong khi các thông số khác thì không.

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

Tôi muốn nói rằng nên sử dụng càng ít ký tự đặc biệt càng tốt trong các 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. Vỏ lạc đà hoặc vỏ 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ĩ rằng thực sự có bất kỳ tiêu chuẩn cứng nào xung quanh REST.

Ngoài ra, tôi nghĩ Gandalf đã đúng, thường thì REST sẽ sạch hơn khi không sử dụng các tham số chuỗi truy vấn, mà thay vào đó, tạo các đườ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