REST&RESTful API

1. REST

REST–> Representational State Transfer–> 表现层状态转化

如果一个架构符合REST原则，则是RESTful架构

关于REST：

• 资源(Resources)

  REST中的表现层指的是"资源"(Resources)的表现层，所谓资源，就是网络上的一个实体，或者说是网络上一个具体的信息。它可以是一段文本，一张图片，一种服务，总之就是一个具体的存在。你可以用一个URI(统一资源定位符)指向它。每种资源对应一个特定的URI。要获取这个资源，访问它的URI即可。所谓“上网”，就是与互联网上一系列的“资源”互动，调用URI。

• 表现层(Representational)

  “资源”是一种实体，它可以有多种外在的表现形式。我们把“资源”具体呈现出来的形式，叫做它的“表现层”。

  例如，文本可以用txt格式表现，也可以用HTML,XML,JSON等格式。图片用JPG,PNG等格式等等。URI只代表资源的实体，不代表它的形式。严格的说，有的网址后的“.html”后缀名是不必要的，因为它表现格式，属于“表现层”范畴，而URI应该只代表“资源”的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept, Content-Type字段指定，这两个字段才是对“表现层”的描述。

• 状态转化(State Transfer)

  访问一个网站，就代表客户端与服务器互动过程，这个过程中，设计到数据与状态的变化。互联网是HTTP协议，无状态的协议。这意味着，所有的状态都保存在服务端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生“状态转化”。而这种转化是建立在表现层上的，所以就是“表现层状态转化”。

  客户端用到的手段，只能是HTTP协议，即四个操作方式–GET/POST/PUT/DELETE

  • GET: 用来获取资源
  • POST: 用来新建/更新资源
  • PUT: 用来更新资源
  • DELETE: 用来删除资源

RESTful架构小结

• 每一个URI代表一种资源
• 客户端与服务器之间，传递这种资源的某种表现层
• 客户端通过四个HTTP动词，对服务段资源进行操作，实现“表现层状态转化”

RESTful设计误区

• 最常见的错误之一–URI包含动词。“资源”表示一种实体，是名词，所以URL不应该有动词，动词应该放在HTTP协议中

  Example: 某个URI是/posts/show/1, show是动词，这个URL应该写出/posts/1,然后用GET方法表示show。

  如果某些动作是HTTP动词表示不了的，应该把动作当成一种资源。比如网上汇款，从账户1到2汇款500元，错误的URI:POST /accounts/1/transfer/500/to/2 正确的写法是把动词transfer改写为名词transaction,资源不能是动词，但可以是一种服务：

  POST /transction HTTP/1.1

  Hots: 127.0.0.1

  from1&to=2&amount=500.00

• 错误：在URI中加入版本号

  http://www.example.com/app/1.0/foo

  http://www.example.com/app/1.1/foo

  因为是不同的版本，可以理解成同一种资源的不同形式的表现，所以应该用同一种URI。版本号可以在HTTP请求头信息的Accept字段区分。参考链接

  $.ajax({
       
      beforeSend: function (req) {
       
          req.setRequestHeader("Accept", "vnd.example-com.foo+json; version=1.1"); 
          },
      type: "GET",
      url: "http://http://www.example.com/foo/12",
      success: function (data) {
       
          /* code elided */
      },
      dataType: "json"
  });
  

restful架构–阮一峰这篇文章的评论区linyang的关于REST的理查德森REST架构成熟度模型link可以mark一下

顺带结合一下评论区的意见：有关rest设计中，向后缀带不带.html, .json等

都可以，带后缀的话对于开发者或者维护人员可以清楚的知道该接口的作用，另外在uri中添加版本号也是可以让uri更加易懂。上述的风格更多是REST架构的风格指导规范。遵循是更好的，就像代码规范一样，不遵循代码规范，也能跑，但不够漂亮

2. RESTful API

api主要方便不同的前端设备与后端进行通信。

参考链接restful 主要就是针对REST架构中的实现例子，这里就不搬运了

3. 基于Springboot设计RESTful API

• RESTful规范：

  GET /collection：返回资源对象的列表（数组）
  GET /collection/resource：返回单个资源对象
  POST /collection：返回新生成的资源对象
  PUT /collection/resource：返回完整的资源对象
  PATCH /collection/resource：返回资源对象(部分信息)(使用较少，与PUT方式合并)
  DELETE /collection/resource：返回一个空文档
  

  注意后面要求的返回的内容

• API设计