Question

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

例如：

api.service.com/helloWorld/userId/x

或

api.service.com/hello_world/user_id/x

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

任何准则都将受到赞赏。

Answer 1

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

因此，您的网址应如下所示（忽略您要求的设计问题： - ））

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

Answer 2

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

Answer 3

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

HelloWorld不是一个非常好的资源类别。它似乎不是一个“东西”。它可能是，但它不是很像名词。 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 4

'UserId'完全是错误的做法。动词（HTTP方法）和名词方法是Roy Fielding对The REST architecture的意义。名词要么是：

集合的东西
thing

一个好的命名惯例是：

[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处有一份我们在prod中使用的指南列表。指南总是值得商榷的......我认为一致性有时比让事情更完美更重要（如果有这样的话）。

Answer 8

我不认为驼峰案例是该示例中的问题，但我想上面示例的更多RESTful命名约定是：

api.service.com/helloWorld/userId/x

而不是使userId成为一个查询参数（这是完全合法的）我的例子表示IMO中的资源是一种更加RESTful的方式。

Answer 9

我想说最好在REST URL中使用尽可能少的特殊字符。 REST的一个好处是它使服务的“界面”易于阅读。 Camel case或Pascal case可能对资源名称（用户或用户）有用。我不认为REST有任何硬性标准。

另外，我认为Gandalf是对的，在REST中通常更清晰，不使用查询字符串参数，而是创建定义您想要处理哪些资源的路径。

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

Answer 10

如果您使用Oauth2对您的客户进行身份验证，我认为您至少需要两个参数名称的下划线：

的client_id
client_secret

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

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

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

10 个答案: