Restful API 最佳实践 (理论篇)

时间：2021-01-10 03:45:45

参考： 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模式进行内容协商
  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（未满足前提条件）
        • Restful API 最佳实践 (理论篇)
  6. 更好的使用数据冗余和链接元素
    • 为了保证 API 的灵活与效率，我们可以提供一个开关参数，如 includeAircraftDetail=true
    • 我们要展示一个文件夹下面所有的文件，并允许用户察看每个文件都允许哪些人编辑，哪些人下载以及将某文件放入收藏夹。这时候，我们可以考虑将这些可以执行的操作的 API 都用链接元素的方式返回给客户端，这样，开发者无需自己拼接 API 调用的 URL，就可以使用，从而降低代码复杂度。

相关文章