在创建REST API时,API中是否有命名约定或实际标准(例如:URL端点路径组件,查询字符串参数)?骆驼帽是常态还是强调?其他?是否有任何有关REST API的命名约定准则?
例如:
api.service.com/helloWorld/userId/x
或
api.service.com/hello_world/user_id/x
注:这不是基于REST的API设计问题,而命名约定准则,以使用为最终路径组件和/或查询使用字符串参数。
任何指导方针,将不胜感激。
在创建REST API时,API中是否有命名约定或实际标准(例如:URL端点路径组件,查询字符串参数)?骆驼帽是常态还是强调?其他?是否有任何有关REST API的命名约定准则?
例如:
api.service.com/helloWorld/userId/x
或
api.service.com/hello_world/user_id/x
注:这不是基于REST的API设计问题,而命名约定准则,以使用为最终路径组件和/或查询使用字符串参数。
任何指导方针,将不胜感激。
我认为你应该避免骆驼帽。规范是使用小写字母。我还要避免下划线和使用破折号,而不是
所以您的网址应该是这样的(忽略你要求:-)设计问题)
api.service.com/hello-world/user-id/x
我不认为骆驼的情况是在该示例中的问题,但我想在上面的例子更RESTful的命名规则是:
api.service.com/helloWorld/userId/x
而不是让userId一个查询参数(这是完全合法的)我的例子表示资源中,国际海事组织,一个更加RESTful的方式。
我想说,最好在REST URL中使用尽可能少的特殊字符。 REST的好处之一是它使服务的“界面”易于阅读。骆驼案或帕斯卡案可能对资源名称(用户或用户)很有用。我认为REST并没有真正的硬标准。
此外,我认为甘道夫是正确的,它在REST中通常更清洁,不使用查询字符串参数,而是创建定义您想要处理的资源的路径。
仔细查看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/
。
重点是提供资源之间的导航路径。
我的问题更多地涉及最终路径名和/或查询字符串参数的命名约定,无论它们是什么。我同意你的设计建议,所以谢谢你,但是这个问题我只是在问关于命名约定。 – jnorris 2009-04-22 18:02:03
号REST无关与URI命名约定。如果您将这些约定作为API的一部分包含在带外,而不是仅通过超文本,那么您的API不是RESTful。
欲了解更多信息,请参阅http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
域名不区分大小写,但URI的其余部分可以肯定是。假设URI不区分大小写是一个很大的错误。
Dropbox,Twitter,Google Web Services和Facebook的REST API全部使用下划线。
'UserId'完全是错误的方法。动词(HTTP方法)和名词方法是Roy Fielding对The REST architecture的意思。名词要么是:
一个很好的命名约定:
[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对他们不友好。
我有一个指南列表http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html,这是我们在产品中使用的。指南总是有争议的......我认为一致性有时比让事情完美(如果有这样的事情)更重要。
如果用的OAuth2验证您的客户我想你会需要强调的至少两个的参数名:
我在使用驼峰我(尚未发布)REST API。在编写API文档时,我一直在考虑将所有内容都更改为snake_case,所以我不必解释为什么Oauth参数是snake_case而其他参数不是snake_case。
这不是基于REST API的设计问题,而命名约定指引,使用使用的最终路径部件和/或查询字符串参数。在你的例子中,路径组件应该像你使用的那样是骆驼大帽,还是下划线? – jnorris 2009-04-22 17:01:39
既然在REST中你的URL是你的接口,那么它就是一个API问题。虽然我不认为你的例子有任何具体的指导方针,但我会亲自去骆驼案例。 – Gandalf 2009-04-22 17:44:16
对于希望在HTTP堆栈的任何级别缓存的资源,您不应该使用查询参数。 – aehlke 2009-07-21 14:34:46