RESTful Web Service最佳实践

000 RESTful Web Service设计的一般步骤

1. 规划数据集 2. 将数据集划分为资源 3. 用URI为资源命名 4. 暴露统一接口的子集 5. 设计来自客户端的表示 6. 设计发给客户端的表示 7. 用超链接把资源与已有资源链接起来 8. 考虑可能的错误

001 资源设计

1. 预定义的一次性资源，比如服务的主页，主要就是服务的索引页，或者目录页 2. 对应于数据项的资源，比如某个用户的一篇日志就是这样一个资源 3. 在数据上的某个算法结果的资源，比如google出来的搜索结果，获取某个用户一段时间内的日志都是这类资源 总的来说，如果每个数据项对应一个资源，那么资源的一个子集也是资源，资源的索引（即目录）也是资源，这取决于你想要 暴露的资源表面积。 资源设计还有一个需要考虑的问题，某一个数据你是需要把它设计为某个或某些资源的属性（子资源），还是直接暴露为单独 的资源。例如要描述两个账户，它们分别是单独的资源，现在有一笔转账要进行，最好的方式是将转账抽象为资源，而不是分别 在账户的下面暴露两个子资源，转入和转出，因为这样可以保证转账操作的原子性。

002 URI设计

服务URI的设计应该具有一定的意义和良好的设计，下面介绍几个可以采用的设计原则 1. 资源暴露的URI应该是主体而非动作，比如要暴露一个提交事务的操作，/do-trasaction/是不适合的，好的设计是设计 /transaction 接口，然后用HTTP动词PUT表示事务的提交 2. 用路径变量对URI进行层次化的划分，通常是从一般到特殊，比如某个用户的某一篇文章可以表示为 /{user-name}/{article-name}， 3. 用逗号和分号分隔同一层次的并列内容，比如对于一个地图服务，可能你需要查询特定经纬度的地理信息，可能的设计是 /position/103.12,37.3

003 统一接口的设计

统一接口的设计是RESTful Web Service的一大特点，通过使用HTTP原有的动词并赋予统一的意义，才能基于资源进行URI设计， 也就是说URI里可以不包含操作信息，这也极大的降低了所需的URI的数量。 1. GET用于资源的获取， 2. PUT用于添加新的资源或者修改资源的状态， 3. DELETE用于删除一个资源， 4. POST用于创建一个从属资源，

004 资源链接的设计

没有链接或者链接少的服务要求客户端熟悉每一个资源对应URI的构造方式，而通过提供链接的方式可以一定程度上屏蔽资源表示的 变化，如果拿编程语言来类比的话就像通过函数或者类将某一些功能封装起来，当你在使用服务的时候只需要循着链接往下就可以了，而 不需要熟悉每一个URI的构造方式。

005 返回值的设计

1. 创建一个资源后，服务器应返回响应代码200('ok')或者异步情况返回201('Created')，并在Location报头给出对应的URI 2. 修改一个资源后，服务器应返回200('OK')，加入本次修改导致了资源URI的改变，返回响应代码301('Moved Permanently')，并在Location报头给出新URI 3. 删除一个资源后，服务器应返回200('OK')

005 常见的错误返回

和统一接口部分的设计一样，RESTful Web Service的错误表示也最大的重用HTTP本身的错误码，下面介绍一些常用的错误码。 1. 加入用户没有获得授权或者授权错误，服务器应返回401('Unauthorized') 2. 对于请求造成了资源的冲突，服务器应返回409('Conflict') 3. 如果在请求时给出了无意义的参数，返回400('Bad Request') 4. 客户端试图获取一个不存在的资源，返回404('Not Found') 5. 如果客户端传输数据格式错误，返回415('Unsupported Media Type')

006 服务的版本化

服务的版本化是当服务规模变大，同时又需要重大的URI更改的时候需要考虑的问题。服务的版本化只需要在设计之初在URI的最顶 层加上版本标识就可以了，例如/v1/user/phone。