Answers:
我认为您应该避免戴骆驼帽。规范是使用小写字母。我也将避免使用下划线,而使用破折号
因此,您的网址应如下所示(忽略您所要求的设计问题:-))
api.service.com/hello-world/user-id/x
适用于Dropbox,Twitter,Google Web Services和Facebook的REST API 均使用下划线。
仔细查看普通Web资源的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/
。
关键是要在资源之间提供导航路径。
“ UserId”完全是错误的方法。动词(HTTP方法)和名词方法是Roy Fielding对REST体系结构的含义。名词是:
一种好的命名约定是:
[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对他们而言不太友好。
不会。REST与URI命名约定无关。如果您将这些约定作为带外API的一部分(而不是仅通过超文本)包含在API中,则您的API不是RESTful的。
有关更多信息,请参见http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
域名不区分大小写,但URI的其余部分当然可以。假设URI不区分大小写是一个很大的错误。
我在产品中使用了http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html上的指南列表。准则总是值得商...的...我认为一致性有时比使事情变得完美(如果有的话)更为重要。
我不认为该示例中的问题是驼峰式的,但是我想上述示例中的RESTful命名约定更为合理:
api.service.com/helloWorld/userId/x
而不是将userId用作查询参数(这是完全合法的),在我的示例中,IMO以一种更加RESTful的方式表示了该资源。
如果您使用Oauth2对客户端进行身份验证,我认为您至少需要为两个参数名加下划线:
我在尚未发布的REST API中使用了camelCase。在编写API文档时,我一直在考虑将所有内容都更改为snake_case,因此不必解释为什么Oauth参数是snake_case而其他参数却不是。
我要说的是,最好在REST URL中使用尽可能少的特殊字符。REST的好处之一是,它使服务的“接口”易于阅读。驼峰式或Pascal式可能适合于资源名称(用户或用户)。我认为关于REST确实没有任何硬性标准。
另外,我认为Gandalf是正确的,在REST中通常不使用查询字符串参数,而是创建定义要处理的资源的路径,这样比较干净。