REST API是否有任何命名约定准则？

Question

在创建REST API时,API中的命名约定是否有任何指导或事实标准(例如:URL端点路径组件,查询字符串参数)？骆驼帽是常态还是下划线？其他？

例如:

api.service.com/helloWorld/userId/x

要么

api.service.com/hello_world/user_id/x

注意:这不是RESTful API设计的问题,而是用于最终路径组件和/或查询字符串参数的命名约定准则.

任何指导方针将不胜感激.

Answer 1

我认为你应该避免使用驼峰帽.规范是使用小写字母.我也会避免使用下划线并使用破折号

所以你的URL应该是这样的(忽略你要求的设计问题:-))

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

Answer 2

仔细查看普通网络资源的URI.这些是你的模板.想想目录树; 使用简单的类Linux文件和目录名称.

HelloWorld不是一个非常好的资源类.它似乎不是一个"东西".它可能是,但它不是很像名词.A greeting是一件事.

user-id可能是你正在取名的名词.但是,您的请求结果只是user_id,这是值得怀疑的.请求的结果更可能是用户.因此,user是你要获取的名词

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

我感觉合理.专注于使您的REST请求成为一种名词短语 - 通过层次结构(或分类法或目录)的路径.使用最简单的名词,尽可能避免使用名词短语.

通常,复合名词短语通常表示层次结构中的另一个步骤.所以你没有/hello-world/user/和/hello-universe/user/.你有/hello/world/user/和hello/universe/user/.或者可能/world/hello/user/和/universe/hello/user/.

关键是在资源之间提供导航路径.

Answer 3

Dropbox,Twitter,Google Web Services和Facebook的REST API 都使用下划线.

Answer 4

'UserId'完全是错误的做法.动词(HTTP方法)和名词方法是Roy Fielding对REST架构的意义.名词是:

1. 事物的集合
2. 一件事

一个好的命名约定是:

[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

其中{media_type}是以下之一:json,xml,rss,pdf,png,甚至html.

可以通过在末尾添加"s"来区分集合,例如:

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

但这意味着你必须记录你把's'和你没有的地方放在哪里.加上半个星球(亚洲人为首发)说的语言没有明确的复数,因此URL对他们不太友好.

Answer 5

不,REST与URI命名约定无关.如果您将这些约定作为API的一部分包含在带外,而不是仅通过超文本,那么您的API不是RESTful.

有关更多信息,请参阅http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Answer 6

域名不区分大小写,但URI的其余部分当然可以.假设URI不区分大小写是一个很大的错误.

Answer 7

我在产品中使用的http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html上有一份准则列表。准则总是值得商...的...我认为一致性有时比使事情变得完美（如果有的话）更为重要。