REST接口设计

REST接口设计

为什么要有REST

在传统上，软件和网络是两个不同的领域，很少有交集；软件开发主要针对单机环境，网络则主要研究系统之间的通信。互联网的兴起，使得这两个领域开始融合，现在我们必须考虑，如何开发“在互联网环境中使用的软件”。RESTful架构，就是目前最流行的一种互联网软件架构。

Web，iOS，Android 作为同等公民调用服务器提供的 API，各自有着各自实现方式。如图

REST的解释

Representational State Transfer （资源表现层状态转化）

资源（Resources)

网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务。你可以用一个URI指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

"上网"，就是与互联网上一系列的"资源"互动，调用它的URI。

表现层（Representation）

"资源"具体呈现出来的形式

比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

状态转换（State Transfer)

访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。

因此，如果客户端通过"某种手段"操作服务器，服务器端就会发生"状态转化"，而这种转化是建立在表现层之上的。具体实例中的"某种手段"，就是HTTP协议（里面四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源，PUT用来更新资源，DELETE用来删除资源。

总结一下RESTful架构：

• 一个URI代表一种资源；

• 客户端和服务器之间，传递的是这种资源的某种表现层；

• 客户端通过“某种手段”，对服务器端资源进行操作，实现"状态转化"。

这是一组架构约束条件和原则，不是一种标准，不这么做你也可以完成任务，只不过你的接口得不到应有的好处。

举个例子

获取用户信息

• 访问地址：

  http://domian/restapi/user.json?id=1

  http://domian/restapi/user/1.json

  http://domian/restapi/user.json?name=foo&addr=bar

• 访问方法：HTTP GET

• 返回格式：

  {
       "id": 1,
      "name": "Jack",
      "addr": "block"
  }
  

增加用户信息

• 访问地址：http://domian/restapi/user.json

• 访问方法：HTTP POST

• 发送数据：

  {
      "name": "Jack1",
      "addr": "block1"
  }
  

• 返回格式：

  {
      "id": 2,
      "name": "Jack1",
      "addr":"block1"
  }
  

修改用户信息

• 访问地址：

  http://domian/restapi/user.json?id=1

  http://domian/restapi/user/1.json

  http://domian/restapi/user.json?name=foo&addr=bar

• 访问方法：HTTP PUT

• 发送数据：

  {
      "id": 2,
      "addr":"bar2"
  }
  

• 返回格式：

  {
      "id": 2,
      "name": "Jack1",
      "addr":"bar2"
  }
  

删除用户信息

• 访问地址：

  http://domian/restapi/user.json?id=1

  http://domian/restapi/user/1.json

  http://domian/restapi/user.json?name=foo&addr=bar

• 访问方法：HTTP DELETE

• 返回格式：

  {
      "detail": "....."
  }