Restful

背景

网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。

定义

REST（表现层状态转换 Representational State Transfer） 指的是一种万维网软件架构风格。满足这种风格的应用程序或设计就是 RESTful。是Roy Fielding博士于2000年在他的博士论文中提出来的一种软件架构风格。

接口基本原则

1、安全可靠，高效易扩展

2、简单明了，可读性强，没有歧义

3、API风格统一，调用规则，传入参数和返回数据有统一的标准

RESTful的设计理念基于HTTP协议，设计原则：

1、HTTPS

    HTTPS为接口的安全提供了保障，可以有效防止通信被窃听和篡改，可以通过 cerbot等工具。 

Attention：非HTTPS的API调用，不要重定向到HTTPS。而要直接返回调用错误以禁止不安全的调用。

2、版本控制

第一种：将版本号直接加入到URL中

https://api.zoe.com/v1
https://api.zoe.com/v2

第二种：使用http请求头的accept字段进行区分（推荐）

Https://api.zoe.com/
Accept:application/prs.zoe.va+json
Accept:application/prs.zoe.va+json

4、用URL定位资源

  在 RESTful 架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，而且所用的名词往往和数据库中的表名对应。一般来说，数据库中的表都是同种记录的 "集合"，所以 API 中的名词也应该使用复数。

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成这样：

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

URI 中需要注意的几点：

• 不用大写
• 用中杠 - 不用下杠 _
• 参数列表要 encode
• URI 中名词表示资源集合，使用复数形式

5、用http动词描述操作
http设计了很多动词来表示不同的操作，RESTful吧这些利用的很好，来表明如何操作资源。

GET（SELECT）：从服务器取出资源（一项或多项）
POST（CREATE）：从服务器新建一个资源
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整属性）
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）
DELETE（DELETE）：从服务器删除资源

下面是一些例子：

POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

7、正确使用状态码

8、统一返回数据格式

对比

REST与RPC
RPC风格曾是Web Service的主流，最初是基于XML-RPC协议，后来渐渐被SOAP协议（简单对象访问协议（Simple Object Access Protocol））取代；RPC风格的服务，不仅可以用HTTP，还可以用TCP或其他通讯协议。但RPC风格的服务，受开发服务采用语言的束缚比较大，如.net框架中，开发web service的传统方式是采用WCF，基于WCF开发的服务即RPC风格的服务，使用该服务的客户端通常要用c#来实现，如果使用Python或其他语言，很难实现可以直接与服务通信客户端。进入移动互联网时代后，RPC风格的服务很难在移动终端使用，而Restful风格的服务，由于可以直接以json或xml为载体承载数据，以HTTP方法为同意接口完成数据操作，客户算的开发不依赖于服务端实现的技术，移动端也可以轻松使用服务，这也加剧了Rest取代RPC为Web Service的主导

参考

RESTful API 设计学习笔记
细说API - 重新认识RESTful