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

在创buildREST API时,API中是否有命名约定或实际标准(例如:URL端点path组件,查询string参数)? 骆驼帽是常态还是下划线? 其他?

例如:

api.service.com/helloWorld/userId/x 

要么

 api.service.com/hello_world/user_id/x 

注意:这不是RESTful APIdevise的问题,而是用于最终path组件和/或查询string参数的命名约定指南。

任何指导方针将不胜感激。

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

所以你的url应该是这样的(忽略你所要求的devise问题:-))

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

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

HelloWorld不是一个非常好的资源类。 这似乎不是一个“事情”。 它可能是,但它不是很像名词般的。 greeting是一件事情。

user-id可能是您正在提取的名词。 然而,可疑的是,你的请求的结果只是一个user_id。 请求的结果更可能是用户。 因此, user是您正在提取的名词

 www.example.com/greeting/user/x/ 

我感觉合理。 着重于使您的REST请求成为一种名词短语 – 通过层次结构(或分类法或目录)的path。 尽可能使用最简单的名词,尽可能避免名词短语。

一般来说,复合名词短语通常意味着层级中的另一个步骤。 所以你没有/hello-world/user//hello-universe/user/ 。 你有/hello/world/user/hello/universe/user/ 。 或者可能/world/hello/user//universe/hello/user/

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

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

'UserId'完全是错误的方法。 动词(HTTP方法)和名词方法是Roy Fielding对于REST体系结构的意义 。 名词是:

  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* 

但是这意味着你必须跟踪你所在的位置,以及你不在的位置。 再加上一半的星球(亚洲人的首发)说的语言没有明确的复数,所以url是不友善的。

不。REST与URI命名约定无关。 如果将这些约定作为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上列出了我们在prod中使用的准则。 指南总是有争议的…我认为一致性有时比让事情完美(如果有这样的事情)更重要。

在这个例子中,我不认为骆驼事件是个问题,但是我想象上面的例子中一个更加RESTful的命名约定是:

api.service.com/helloWorld/userId/x

而不是让userId一个查询参数(这是完全合法的)我的例子表示资源中,国际海事组织,一个更加RESTful的方式。

我想说,最好在REST URL中使用尽可能less的特殊字符。 REST的好处之一是它使服务的“接口”易于阅读。 骆驼案件或帕斯卡案件可能是好的资源名称(用户或用户)。 我认为REST并没有真正的硬标准。

另外,我认为Gandalf是正确的,在REST中通常不使用查询string参数,而是创build定义要处理的资源的path。

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

如果你使用Oauth2validation你的客户端,我认为你至less需要两个参数名称的下划线:

  • CLIENT_ID
  • client_secret

我在我的(尚未发布的)REST API中使用了camelCase。 在编写API文档的时候,我一直在想把所有东西都改成snake_case,所以我不必解释为什么Oauth params是snake_case,而其他params则不是。

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