Restful API 最佳实践 (理论篇)

参考： http://www.ibm.com/developerworks/cn/web/1103_chenyan_restapi/

规划好 资源标示结构 和 URI模式， 是API设计成功的关键

原创文章，转载请注明：http://www.cnblogs.com/ganiks/

1. 规划资源标识结构和URI模式
   1. 规划基本资源类型
      • 针对一个文档的评论， URI 模式可以设计成如下：/ 文件夹 / [ 文件夹名 ] / 文件 / [ 文件名 ] / 评论 / [ 评论唯一标示 ]
   2. 规划集合资源类型
      • 使用过滤条件
        • / 环境工程系 / 学生 ? 籍贯 = 北京 & 性别 = 女
      • 使用排序
        • ?sortOrder=asc&sortField=age
      • 使用分页
        • / 所有学生 ?page=5&pagesize=50
   3. 一些特殊资源类型
      • 如果我们来定义一个新的集合 ----“我检出的文档”，用创建一个集合资源来对应检出（创建一个文档锁），用删除一个集合资源来对应检入（删除一个文档锁)
      • 在 REST 这个以名词为核心的构架结构中，当你遇到一些动词特性比较强的操作，而又很难用原始资源的增删改查来匹配的时候，不妨换个思路， 通过引入新的逻辑资源集合的方式， 来进行 API 的设计与规划。
2. 理解和使用内容协商
   1. 使用URL参数进行内容协商
      • http://restapi/news/26?format=xml
      • 使用 URL 参数，简单灵活，但是也由此带来了设计上的随意和不标准;过多的参数会导致 URL 的可读性变差，更有甚者，可能会导致 URL 过长，超出规范，API 请求无法执行
   2. 使用Accept头进行内容协商
      • Accept:application/json,text/html
      • Accept-Charset:utf-8
      • Accept-Encoding:gzip,deflate,sdcn
      • Accept-Language:zh-CN,zh;q=0.8,en-US;q=0.6,en;q=0.4
   3. 使用URI模式进行内容协商
      • http://restapi/news/26/json
      • http://restapi/news/26/xml
3. 正确的使用HTTP响应代码
   • 200 OK
   • 201 Created
   • 202 Accepted
   • 204 No Content
   • 301 Moved Permanently
   • 302 Found
   • 304 Not Modified
   • 305
   • 400 Bad Request
   • 401 UnAuthorized
   • 403 Forbidden
   • 404 Not Found
   • 405 Method Not Allowed
   • 500 Internal Server Error
   • 501
   • 502 Bad GateWay
   • 504 GateWay Timeout
   • 505
4. 使用HTTP头处理缓存
   • 缓存控制
     • Cache-control
       • private
       • no-cache
       • max-age=600
       • must-revalidate
     • Expires
   • 条件请求与电子标签
     • 很多时候，内容可能几个小时甚至几天都不会发生变动
     • HTTP头中返回内容的最后修改时间Last-Modified
     • 根据服务器内容生成电子标签ETag
     • 下次请求的时候会使用If-Modified-Since或者If-None-Match头信息把上次请求到的时间戳或者Etag传给服务器，服务器端进行判断后：
       • 返回给用户最新的内容
       • 返回HTTP304，内容没有变化
5. 使用HTTP头处理并发
   • 条件请求
     • 在发出修改请求的同时，在HTTP头中使用If-Not-Modified-Since或者If-Match头信息，把获取数据时得到的时间戳或者电子标签传给服务器
     • 服务器通过这个与当前内容比较，可知修改请求是否是针对当前内容提出的。
       • 是，则修改
       • 不是，返回HTTP412（未满足前提条件）
       • 
6. 更好的使用数据冗余和链接元素
   • 为了保证 API 的灵活与效率，我们可以提供一个开关参数，如 includeAircraftDetail=true
   • 我们要展示一个文件夹下面所有的文件，并允许用户察看每个文件都允许哪些人编辑，哪些人下载以及将某文件放入收藏夹。这时候，我们可以考虑将这些可以执行的操作的 API 都用链接元素的方式返回给客户端，这样，开发者无需自己拼接 API 调用的 URL，就可以使用，从而降低代码复杂度。