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

Posted 2023-02-22

【中文标题】REST API 是不是有任何命名约定准则？ [关闭]

【英文标题】：Are there any naming convention guidelines for REST APIs? [closed]REST API 是否有任何命名约定准则？ [关闭]

【发布时间】：2010-10-21 03:54:03

【问题描述】：

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

例如：

api.service.com/helloWorld/userId/x

或

api.service.com/hello_world/user_id/x

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

任何指南都将不胜感激。

【参考方案1】：

我不认为骆驼案例是该示例中的问题，但我认为上述示例的更 RESTful 命名约定将是：

api.service.com/helloWorld/userId/x

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

【讨论】：

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

好吧，既然在 REST 中你的 URL 就是你的接口，那么它就是一个 API 问题。虽然我认为您的示例没有任何特定的指导方针，但我个人会选择骆驼案。

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

@aehlke 正好相反也是如此。如果您不想缓存查询参数，请对参数使用 GET 样式，~或~ 确保为您不想缓存的任何内容修改/插入反缓存标头。此外，还有一些标头是对象/页面返回的哈希值，使用它来指示您想要缓存的内容的更改，但在有编辑时更新。

@aehlke 了解缓存并添加它。我记得一个 CodeCamp 演示文稿，其中一个加速器正在执行所有这些标头，然后在其内容更改时更改文件名和对它的所有引用，以便在长时间缓存后让浏览器和代理服务器提供更新的版本。放。以下是所有血腥细节：developers.google.com/speed/docs/best-practices/caching

【参考方案2】：

我会说最好在 REST URL 中使用尽可能少的特殊字符。 REST 的好处之一是它使服务的“界面”易于阅读。 Camel 大小写或 Pascal 大小写可能适合资源名称（用户或用户）。我认为 REST 并没有真正的硬标准。

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

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

【参考方案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/。

重点是提供资源之间的导航路径。

【讨论】：

我的问题更多是关于最终路径名和/或查询字符串参数的命名约定，无论它们可能是什么。我同意你的设计建议，所以谢谢你，但这个问题我只是询问命名约定。

请注意，没有什么可以阻止您将 REST 用于非分层资源。您使用的实际 URI 命名约定无关紧要，只需使用您认为好看且易于在服务器上解析的任何内容即可。客户端不应该知道任何有关生成 URI 的信息，因为您需要通过响应中的超文本将 URI 发送到资源。

【参考方案4】：

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

所以你的网址应该是这样的（按照你的要求忽略设计问题:-)）

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

【讨论】：

根据 RFC2616，只有 URL 的方案和主机部分不区分大小写。 URL 的其余部分，即路径和查询应该区分大小写。 w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3

丹尼尔，你是对的，感谢您指出这一点。然而，事实上我们通常期望 url 忽略大小写，尤其是资源名称部分。 userid 和 UserId 行为不同是没有意义的（除非其中一个返回 404）

@LiorH：为什么你认为区分大小写“没有意义”？许多其他上下文对良好效果是区分大小写的。有一些 Web 服务（例如 Amazon S3）确实强制 URL 端点区分大小写，我认为这非常合适。

@Dennis Windows 服务器文件系统默认不区分大小写，除非我严重误会technet.microsoft.com/en-us/library/cc725747.aspx

@samspot 好一个！我认为 Windows 在创建服务器时会直接使用区分大小写的文件名。哇，他们仍在尽可能长时间地推动他们的方式，即“1 MicroSoft Way”。 ;-)

【参考方案5】：

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

欲了解更多信息，请参阅http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

【讨论】：

休息一下...拥有漂亮的 URL 仍然很好。

同意@HDave，拥有易于理解的 URL 非常符合 REST 的精神。您正在使用 URL，为什么不希望它们像代码中的变量和参数名称一样容易理解？

@mahemoff 对不起，这是我超级迂腐。但是您的 URL 看起来与 REST 无关。这并不意味着拥有它们不是一件好事，它们只是与 REST 描述的内容正交。说 REST 是以这种方式构建 URL 是一种误导，因为它导致人们仅仅因为 RPC API 具有可读/结构化的 URL 而将它们描述为 REST。

总之，漂亮的 URL 很棒，每个人都应该拥有它们。但它与 REST 无关。

@aehlke 感谢您清除此问题。 Rest 与 URL 结构无关。我不明白为什么人们很难理解。

【参考方案6】：

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

【参考方案7】：

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

【讨论】：

这样做的副作用之一是下划线的“单词”在谷歌的搜索索引中保持完整。连字符被分成单独的单词。

示例：dev.twitter.com/docs/api/1.1

虽然 Google Maps API 确实使用下划线，但 Google Style Guide 需要驼峰式大小写。 Google+ API 和 Custom Search API 等使用 Camel Case。

然而他们仍然使用'-'作为这些网址的分隔符：P developers.google.com/custom-search/json-api/v1/reference/cse/… developers.google.com/+/best-practices dev.twitter.com/overview/case-studies 另一方面，他们在查询参数中使用驼峰式。

没人知道...

【参考方案8】：

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

【讨论】：

var 是什么意思？如果我按名称搜索用户，例如 .../user/username/tomsawyer ?

如果您有三个变量 (var)，分别命名为 x、y、z，那么您的 URL 将如下所示：sub.domain.tld/x/value_of_x/y/value_of_y/z/value_of_z

@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 的值。

这是我认为的最佳答案，也是国际化思考的荣誉。

【参考方案9】：

我在http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html 有一个指南列表，我们在 prod 中使用了这些指南。指导方针总是值得商榷的......我认为一致性有时比让事情变得完美（如果有的话）更重要。

【参考方案10】：

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

client_id client_secret

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

见：https://www.rfc-editor.org/rfc/rfc6749