1. 引言

  基于Http协议的RESTful风格API的思想是：一切皆资源，把API视为对资源的操纵方法。用URL（统一资源定位符）来标定资源，用HTTP动词来表示对资源的操纵行为。
  我们收发快递时的地址信息，就是一种统一资源定位符的思想体现。通过概念名词的层层限定，来逐步缩小范围，最终定位到目标。例如“山东省威海市高区xx街道xx号503 余先生”。微服务的URL组织也是基于此种思想。例如：GET http://https://github.com/taosdata/TDengine/tree/2.6
  在实际的服务开发过程中，面对的场景多种多样，用“HTTP动词+一系列名词组成的URL”（此处主要是URL的path）表达出一个API的主要功能，在很多时候是不准确和很困难的。在实际开发过程中经常会打破这一准则，RESTful风格的思想是非常好的，只是有一定的局限性，开发人员/团队需要建立与RESTful路径组织思想兼容的准则，以覆盖其所不适用的场景。
  API的路径组织是一个与开发人员自主意识高度相关的活动，不同的人在不违反准则的前提下，组织的同一API的路径可能有些许不同，但这也是没关系的。关于API路径的组织并没有统一的规范，每个公司或团队都可能有与它业务场景和开发习惯相适应的API组织规范。本规范只在我带领的团队内部使用，公开以供有需要的读者借鉴。

2. HTTP基础

  一般的http的url路径格式：http://<域名或ip>[:端口][/路径][?参数名1[=参数值1]&...]

   关于HTTP动词的使用解释，可参看本人的另一篇文档《HTTP基础及跨域》

  基于http的REST API主要有这几种传参方式：

• QueryParam。查询参数可以是url中“?”后面的参数，也可以是POST请求时form形式的参数。它是本团队建议采用的主要传承方式。
• BodyParam。HttpBody参数，因为它不带名，内容形式自由，长度可变。
• HeaderParam。存在于Http head中的参数
• PathParam/PathVariable。路径中的参数，例如：/cim-class/{name}/attributes。此种传参方式如果不是使用场景下非常契合RESTful思想和利于路径的组织，本团队内不推荐使用。路径传参这种形式的API，网关检索匹配相对来说比固定path的更繁琐。而且参数内容格式太复杂或过长，都极有可能引入意外的问题。

3. 路径的组织规范。

1. 确定API的操作目标对象，尽可能用名词来组织路径，用资源定位的思想来描述。
2. 如果http动词的公认含义不能准确表达对对象的操纵行为，可以用"_动词"来表达。例如：启动，"_start"；停止，"_stop"。这个动词只能是path的最后一段，不能出现在中间。
3. 合理分拆，对齐原则。例如，查一个表的数据的路径是/rdb/table/data，现在还需要一个查询表的定义信息的接口，为了对齐，就可以将其组织为/rdb/table/schema，而不应该定义成/rdb/tableSchema。
4. 不用复数词，用单数词。配合all、many、one，来使用。例如获取数据库中所有表的表名，路径可以组织为：/rdb/table/name/all；通过表名获取一个表的模式信息，路径可以组织为：/rdb/table/schema/one/ofName。
5. 合理使用极少数介词。尽可能用of、极少数用：for、to。例如获取一个MySQL的select操作模版。路径可以组织为/rdb/sql/template/mysql/ofSelect。介词的组合词允许出现在路径中间位置，但不应该出现在第一段，原则上尽可能靠后。