×

web开发 RESTful API

RESTFul API的设计原则整理

feihu1996 feihu1996 发表于2017-11-05 10:51:36 浏览475 评论2

2人参与发表评论

RESTFUL API的设计原则整理

REST简介

REST是什么

  • 万维网软件架构风格
  • 用来创建网络服务

为何叫REST

  • Representational State Transfer

    • Representational

      • 数据的表现形式(JSON、XML、……)
    • State

      • 当前状态或者数据
    • Transfer

      • 数据在互联网上进行传输

        • 比如,数据从服务端传到客户端

REST的六大限制

  • 客户-服务器(Client-Server)

    • 关注点分离的软件架构思想
    • 服务端专注数据存储,提升了简单性
    • 客户端专注用户界面,提升了可移植性
  • 无状态(Stateless)

    • 所有用户会话信息都保存在客户端
    • 每次请求必须包括所有信息,不能依赖上下文信息
    • 服务端不用保存会话信息,提升了简单性、可靠性、可见性
  • 缓存(Cache)

    • 所有服务端响应都要被标为可缓存或不可缓存
    • 减少前后端交互,提升了性能
  • 统一接口(Uniform Interface)

    • 接口设计尽可能遵循同一个规范,提升了简单性、可见性

    • 接口与实现解耦,使前后端可以独立开发迭代

    • 统一接口的限制

      • 资源的标识

        • 资源是任何可以命名的事物,比如用户、评论等
        • 每个资源可以通过URI被唯一地标识
      • 通过表述来操作资源

        • 表述就是Representation,比如JSON、XML等
        • 客户端不能直接操作(比如SQL)服务端资源
        • 客户端应该通过表述(比如JSON)来操作资源
      • 自描述消息

        • 每个消息(请求或响应)必须提供足够的信息让接受者理解
        • 媒体类型(application/json、application/xml)
        • HTTP方法:GET(查)、POST(增)、DELETE(删)
        • 是否缓存:Cache-Control
        • 其他更多请求/响应头
      • 超媒体作为应用状态引擎

        • 超媒体

          • 带文字的链接
        • 应用状态

          • 一个网页/json
        • 引擎

          • 驱动、跳转
        • 合起来

          • 点击链接跳转到另一个网页/json
        • 让开发者更加方便的找到其他相关接口

  • 分层系统(Layered System)

    • 每层只知道相邻的一层,后面隐藏的就不知道了
    • 客户端不知道是和代理还是和真实服务器通信
    • 中间件
    • 其他层:安全层、负载均衡、缓存层等
  • 按需代码(Code On Demand)

    • 客户端可以下载运行服务端传来的代码(比如JS)
    • 通过减少一些功能,简化了客户端

RESTful API简介

什么是RESTful API

  • 符合REST架构风格的API

RESTful API具体什么样子

  • 基本的URI,如https://api.github.com/users
  • 标准HTTP方法,如GET、POST、PUT、PATCH、DELETE
  • 传输的数据媒体类型,如JSON、XML

现实举例

  • GET /users # 获取用户列表
  • GET /users/12 # 查看某个具体的用户
  • POST /users # 新建一个用户
  • PUT /users/12 # 更新用户12
  • DELETE /users/12 # 删除用户12

RESTful API设计参考GitHub API V3

RESTful API 最佳实践

协议

  • 客户端与API之间使用HTTPS协议通信

域名

版本

路径

  • “路径”表示表示API的具体网址

  • 在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词(不要出现大写字母)

  • 所用的名词往往与数据库的表名对应,且通常是复数形式

  • URI使用嵌套表示关联关系,如/users/12/repos/5

  • 如:https://api.feihu1996.cn/v1/blogs,https://api.feihu1996.cn/v1/comments

  • 不符合CRUD的情况

    • POST/动词/子资源
    • POST/子资源?action=xxx
    • POST/子资源/action的名词

HTTP动词

  • 对于资源的具体操作类型,由HTTP动词表示

  • 常用的HTTP动词(括号里是对应的SQL关键字)

    • GET(SELECT):从服务器取出资源(一项或多项)
    • POST(CREATE):在服务器新建一个资源
    • PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
    • PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)
    • DELETE(DELETE):从服务器删除资源
    • HEAD:获取资源的元数据
    • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的
  • 示例

    • GET /blogs:列出所有博客
    • POST /blogs:新建一个博客
    • GET /blogs/ID:获取某个指定博客的信息
    • PUT /blogs/ID:更新某个指定博客的信息(提供该博客的全部信息)
    • PATCH /blogs/ID:更新某个指定博客的信息(提供该博客的部分信息)
    • DELETE /blogs/ID:删除某个博客
    • GET /blogs/ID/comments:列出某个指定博客的所有评论
    • DELETE /blogs/ID/comments/ID:删除某个指定博客的指定评论

过滤信息

  • 如果记录数量很多,服务器不可能都将它们返回给客户端。API应该提供参数,过滤返回结果

  • 限制响应的内容必须要符合查询条件

  • 限制返回结果只能包含指定的字段

  • 常见的过滤参数列举

    • ?limit=10:指定返回记录的数量
    • ?offset=10:指定返回记录的开始位置。
    • ?page=2&per_page=100:指定第几页,以及每页的记录数。
    • ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
    • ?blog_type_id=1:指定筛选条件
    • ?q=keyword:关键词模糊搜索

状态码

返回结果

  • 返回结果的数据格式必须使用JSON

  • 如果状态码是4xx,就应该向用户返回错误信息和错误码,并按照统一通用的格式规范化错误信息

  • 针对增删改查等不同操作,服务器向用户返回的结果应该符合以下规范

    • GET /collection:返回资源对象的列表(数组)
    • GET /collection/resource:返回单个资源对象
    • POST /collection:返回新生成的资源对象
    • PUT /collection/resource:返回完整的资源对象
    • PATCH /collection/resource:返回完整的资源对象
    • DELETE /collection/resource:返回一个204状态码,表示没有内容,但是成功了

Hypermedia API

  • RESTful API在返回结果中提供链接,连向其他API方法,使得客户端不查文档,也知道下一步应该做什么

  • 如:当客户端向api.feihu1996.cn的根目录发出请求,会得到这样一个文档

    { 
          "link": { 
                  "rel":   "collection https://www.feihu1996.cn/blogs", 
                  "href":  "https://api.feihu1996.cn/blogs", 
                  "title": "List of blogs", 
                  "type":  "application/vnd.yourformat+json" 
              } 
      }
  • 文档中有一个link属性,客户端读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址)。href表示API的路径。title表示API的标题。type表示返回类型

API身份认证

  • 使用Token令牌来做用户身份的校验与权限分级,而不是Cookie

API文档

  • 有一份漂亮的文档

群贤毕至

访客
feihu1996 feihu19962018-12-11 14:25:11 | 回复 [F]decline[/F][F]laughs[/F][F]naughty[/F][F]laughing[/F][F]laugh[/F]
feihu1996 feihu19962019-01-25 12:50:58 | 回复 好羞射,这文章棒棒哒~顶博主!