REST API是否有任何命名约定准则?[关闭]


211

创建REST API时,API中是否有任何有关命名约定的准则或事实上的标准(例如:URL端点路径组件,querystring参数)?骆驼帽是规范,还是下划线?其他?

例如:

api.service.com/helloWorld/userId/x

要么

api.service.com/hello_world/user_id/x

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

任何准则,将不胜感激。

Answers:


150

我认为您应该避免戴骆驼帽。规范是使用小写字母。我也将避免使用下划线,而使用破折号

因此,您的网址应如下所示(忽略您所要求的设计问题:-))

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

187
根据RFC2616,仅URL的方案和主机部分不区分大小写。URL的其余部分,即路径和查询应区分大小写。w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Darrel Miller 2010年

10
丹尼尔,您说得对,谢谢您指出这一点。但是,事实上,我们通常希望url忽略大小写,尤其是资源名称部分。userid和UserId的行为不同(除非其中一个返回404)是没有意义的
LiorH 2010年

18
@LiorH:为什么您认为区分大小写“毫无意义”?许多其他情况也对区分大小写敏感。有一些Web服务(例如Amazon S3)确实对URL端点强制区分大小写,我认为这是非常适当的。
汉克,

6
@Dennis Windows服务器文件系统默认情况下不区分大小写,除非我非常误解technet.microsoft.com/en-us/library/cc725747.aspx
samspot 2012年

5
@samspot好一个!我以为Windows在创建服务器时会直接使用区分大小写的文件名。哇,他们一直在尽其所能地推动他们的发展,即“ 1 MicroSoft Way”。;-)
丹尼斯

87

适用于DropboxTwitterGoogle Web ServicesFacebook的REST API 均使用下划线。


24
这样做的副作用之一是,在Google的搜索索引中,下划线的“单词”会保持完整。被Hyhenated的被分解成单独的单词。
丹尼斯


11
虽然Google Maps API确实使用下划线,但《Google风格指南》要求使用Camel Case。在Google+的API自定义搜索API,除其他外,使用驼峰。
本杰明

2
然而,他们仍然使用“ - ”作为分隔符这些网址:P developers.google.com/custom-search/json-api/v1/reference/cse/... developers.google.com/+/best-practices dev.twitter。 com / overview / case-studies 另一方面,它们在查询参数中使用camelCase。
Mattias

1
没人知道...
Piotr Kula

84

仔细查看普通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/

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


4
我的问题更多是关于最终路径名和/或querystring参数的命名约定,无论它们可能是什么。我同意您的设计建议,非常感谢,但是关于这个问题,我只是想问一下命名约定。
jnorris

1
只是要注意,没有什么阻止您将REST用于非分层资源。您使用的实际URI命名约定并不重要,只需使用您认为看起来不错并且易于在服务器上解析的内容即可。客户端对生成URI一无所知,因为您需要通过响应中的超文本将URI发送到资源。
aehlke

30

“ UserId”完全是错误的方法。动词(HTTP方法)和名词方法是Roy FieldingREST体系结构的含义。名词是:

  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对他们而言不太友好。


{var}是什么意思?如果我通过名称搜索用户,例如... / user / username / tomsawyer?
汉斯·彼得·斯托尔2012年

1
如果您有三个分别名为x,y,z的变量(var),则您的URL如下所示:sub.domain.tld / x / value_of_x / y / value_of_y / z / value_of_z
Dennis

@hstoerr为了确保我很清楚,大多数脚本语言都使用某种“弯括号变量替换”。因此,{var}表示其中存在某个变量(它的名称),因此以下{value}是{var}之前的值。例如:sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json]将尝试从yelp.com获取json结果以显示食物值高于4
丹尼斯

在我看来,这是国际思考的最佳答案。
beiller

13

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

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


44
休息一下...拥有漂亮外观的URL仍然很不错。
HDave 2012年

1
同意@ HDave,REST的精神是拥有易于理解的URL。您正在使用URL,为什么不希望它们像代码中的变量和参数名称一样容易理解?
mahemoff 2012年

4
@mahemoff对不起,这是我超级学究。但是您的URL外观与REST无关。这并不意味着它们不是一件好事,它们只是与REST描述的正交。说REST是用这种方式构造URL是一种误导,因为它导致人们将RPC API描述为REST只是因为它们具有可读/结构化的URL。
aehlke

5
总之,外观漂亮的URL很棒,每个人都应该拥有它们。它与REST无关。
aehlke 2012年

1
@aehlke感谢您解决此问题。剩下的与URL结构无关。我不明白为什么人们很难理解。
user1431072 2014年

9

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



2

我不认为该示例中的问题是驼峰式的,但是我想上述示例中的RESTful命名约定更为合理:

api.service.com/helloWorld/userId/x

而不是将userId用作查询参数(这是完全合法的),在我的示例中,IMO以一种更加RESTful的方式表示了该资源。


这不是RESTful API设计的问题,而是用于最终使用的路径组件和/或查询字符串参数的命名约定准则。在您的示例中,路径组件应该像以前使用的那样放在驼峰帽中,还是要加下划线?
jnorris

好吧,因为在REST中,URL是您的接口,所以这是一个API问题。尽管我不认为您的示例有任何指导原则,但我个人会使用骆驼保护套。
甘道夫

您不应该对要在HTTP堆栈的任何级别上缓存的资源使用查询参数。
aehlke

@aehlke恰恰相反也是如此。如果您不想缓存查询参数,请对参数使用GET样式,〜OR〜使DARN SURE修改/插入不需要缓存的内容的反缓存头。另外,还有一些标头,它是对象/页面回退的哈希值,用于指示您希望缓存的事物的更改,但是在进行编辑时会进行更新。
丹尼斯

@aehlke了解有关缓存的信息并正在添加它。我记得一个CodeCamp演示,其中加速之一是完成所有这些头文件,然后在文件内容更改时更改文件名及其所有引用,以使浏览器和代理在经过很长的缓存时间后才可以使用较新版本的服务器组。以下是所有详细信息:developers.google.com/speed/docs/best-practices/caching
丹尼斯(Dennis)

2

如果您使用Oauth2对客户端进行身份验证,我认为您至少需要为两个参数名加下划线:

  • client_id
  • client_secret

我在尚未发布的REST API中使用了camelCase。在编写API文档时,我一直在考虑将所有内容都更改为snake_case,因此不必解释为什么Oauth参数是snake_case而其他参数却不是。

请参阅:https//tools.ietf.org/html/rfc6749


0

我要说的是,最好在REST URL中使用尽可能少的特殊字符。REST的好处之一是,它使服务的“接口”易于阅读。驼峰式或Pascal式可能适合于资源名称(用户或用户)。我认为关于REST确实没有任何硬性标准。

另外,我认为Gandalf是正确的,在REST中通常不使用查询字符串参数,而是创建定义要处理的资源的路径,这样比较干净。

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

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.