在创建REST API时,API内的命名约定是否有任何指导方针或事实上的标准(例如:URL端点路径组件,查询字符串参数)?驼色大写,还是下划线?其他人呢?

例如:

api.service.com/helloWorld/userId/x

or

api.service.com/hello_world/user_id/x

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

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


当前回答

我在http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html上有一份我们在prod中使用的指南清单。指南总是有争议的…我认为一致性有时比把事情做到完美更重要(如果有的话)。

其他回答

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

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

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

我觉得你应该避免戴驼峰帽。标准是使用小写字母。我还会避免使用下划线,而是使用破折号

所以你的URL应该是这样的(忽略你所要求的设计问题:-))

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

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

HelloWorld并不是一个很好的资源类。它看起来并不是一个“东西”。它可能是,但不太像名词。问候是一件事。

User-id可能是你取回的名词。然而,请求的结果仅仅是一个user_id是值得怀疑的。请求的结果更有可能是一个User。因此,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/。

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

我在http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html上有一份我们在prod中使用的指南清单。指南总是有争议的…我认为一致性有时比把事情做到完美更重要(如果有的话)。