REST服务的URI设计

REST服务的URI设计

第一：前言

我们一般写API常用的逻辑思维是以“动作”为中心，比如购买商品，要查询商品列表添加购物车，提交订单，写接口不外乎“listGoods, addCarts，submitOrders”等， 这些接口常常是表达某种动作。
而REST服务抽象出了“资源”的概念，API设计将不再以执行了什么动作为中心，而是以资源为中心。一些对资源的通用操作有添加，取得，修改，删除，以及对符合特定条件的资源进行列表操作。
与之对应的是系统设计步骤的不同，首先想的不是“为了完成系统业务需要哪些动作，而是为了完成系统业务需要哪些资源。
在设计URI之前，我们需要了解一些概念，比如何为资源？

当然对于我们实用主义的人来说，这些概念了解了解即可，这些资源概念即使在以动作为中心的API设计里依然存在，只是我们没用明确的红线标识出来而已，不要被“资源”的概念进入坑里了。

RESTful的定义是HTTP 1.1标准的一部分。具体实现和语言无关。而解析RESTful URL是由实现HTTP服务的组件来进行的，具体是哪种并不重要。
RESTful是一种（推荐的）命名规范和设计思路。所以你并不需要强迫自己按照它的方式走。只是这是一种推荐而已。不要为了RESTful而RESTful

第二：什么是资源，怎么抽离

REST里一切都是资源，它是概念上的一种抽象，比如电商平台，资源肯定包括订单，购物车，商品，商品分类，帐户等。
判断资源的抽象是否合理，一般使用如下方法：
对应资源的CRUD是否产生意义。比如删除商品，那该商品必需没有了，说明对资源的操作产生了意义。比如如果把商品的分布功能也抽成的资源，那对删除某页的商品后，该页数据并没消除而是被后面一页替换了，即做删除并没有产生意义（当然对整体而言数据变少了，但对应的资源是“商品”而不是“商品分布”资源）
资源抽象出来有主资源和子资源之分。主资源实际上就是能够独立存在的一系列资源。而子资源则需要依附于主资源之上才能表达实际的意义。同时各个子资源也可能拥有自身的子资源。比如把主资源删了，但子资源依然可以被其它资源重用，那这个子资源可视为主资源。
区分主资源和子资源实际上是为了URI命名做准备的。

第三：URI命名规范

抽象出资源概念后，我们就可以为资源设计URI了。
这里使用的“根路径”是“/api”，即统一的API相对根路径入口，相信使用过SpringMVC的同学都明白。以下以订单“orders”资源为例。
“orders”是个主资源，由于主资源是一类独立的资源，因此它应该直接置于/api下。如下

  /api/orders

1.获取订单类型的特定实例，在主资源的URI里加上资源ID，通俗说法是根据cd值查询订单

/api/orders/1234

2.按帐户主键分布查询

/api/orders/1(acctPk)/page

3.不可避免的一个问题是参数是放在URI里还是请求参数里。我的原则是如下2点：
1.任何参数都可以放在请求参数里，因为请求参数它不会影响URI路径，但放在URI里就不一样的，对于确定不了的就用请求参数携带数据。

2.对于多个（至少2个）可选的参数放在请求参数里。对于单个可放在URI里。比如
2个以上的参数：以egoods中的手机为例。在选择手机时，用户可以选择品牌以及颜色。如果将品牌和颜色都定义在相对URL中，那么具有特定品牌和颜色的手机将可以通过两个不同的URL访问：/api/mobiles/brand/{brand}/color/{color}以及/api/mobiles/color/{color}/brand/{brand}。就用户而言，其并无法了解这两个URL所表示的是同一类资源还是不同类型的资源。当然，您可以说，我们只用/api/mobiles/brand/{brand}/color/{color}。但是该URL将无法处理用户仅仅选择了颜色，却没有选择品牌的情况。
单个参数：比如订单下某个cd的实例
orders/1
查询cd值是1的订单，因为cd值是条件固定的，可放在URI里。但如果按订单号和订单名称云查询就不一样的，如果放在URI里有前后顺序，有可能没先订单名称或cd。就像上面的2个以上参数一样。
有种特殊的情况，“条件固定且条件顺序固定”，也可以放在URI里。
总的来说，放在哪里并没有明确的要求。不要为了规范而规范。

第四：重点

使用HTTP动词表示请求的目的。
比如：
GET /tickets # 获取ticket列表
GET /tickets/12 # 查看某个具体的ticket
POST /tickets # 新建一个ticket
PUT /tickets/12 # 更新ticket 12.
DELETE /tickets/12 #删除ticekt 12
可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。接口名称一样，但使用不同的HTTP动态会进入不同的接口。