# RESTful入门

## 1. REST简介

和RPC一样，都是目前比较主流的URL链接风格，也可以说是web服务的一种架构风格。REST全称Representational State Transfer，表现层状态转移。用一句话简单的概括就是URL定位资源，用HTTP动词（GET，POST，DELETE，PUT）描述操作。其实它真正的全称是Resource Representational State Transfer，看字面意思就是资源在网络中以某种表现形式进行状态转移。我们分开来解读：

* Resources：资源，即数据，比如friends，books等；
* Representational ：某种表现形式，比如用json，xml，jpg等；
* State Transfer：状态变化，通过HTTP动词实现。

符合rest类型的结构就是Restful。

举个简单的例子：

```
非REST的url：http://...../queryItems.action?id=001&type=T01
REST的url风格：http://..../items/001
```

再比如：

```
http://api.qc.com/v1/newsfeed: 某人的新鲜事; 
http://api.qc.com/v1/friends: 某人的好友列表;
http://api.qc.com/v1/profile: 某人的详细信息;
然后用HTTP协议里的动词来实现资源的添加，修改，删除等操作。即通过HTTP动词来实现资源的状态扭转：
GET http://api.qc.com/v1/friends: 获取某人的全部好友列表;
GET http://api.qc.com/v1/friends/{id}: 获取某人的指定好友;
POST http://api.qc.com/v1/friends: 添加好友;
DELETE http://api.qc.com/v1/friends/{id}: 根据id删除好友;
PUT http://api.qc.com/v1/friends/{id}: 根据id更新好友;
禁止使用类似这样的URL：http://api.qc.com/v1/deleteFriend
```

## 2. 为什么用Restful

为了通过统一的接口为web，Android，IOS提供服务，对于微博开放平台，微信公共平台等，他们不需要有显式的前端，只需要一套提供服务的接口，也是Restful是它们最好的选择。

## 3. 如何设计

### 3.1 URL使用名词而不是动词，且推荐用复数

在restful架构中，每个URL代表一种资源，所以网址中不能有动词，只能有名词。

反例：

```
/getBooks
/addBook
/updateBook
/deleteBook?id=10
```

正例：

```
GET /books
POST /books
PUT /books/{id}
DELETE /books/{id}
```

### 3.2 保证head和get方法是安全的

head和get方法不会对资源的状态有所改变（污染），比如严格杜绝如下情况：

```
GET /deleteBook?id=10
```

GET、HEAD和OPTIONS均被认为是安全的方法，而PUT、POST、DELETE等请求都是不安全的（会修改数据 ）。

### 3.3 资源的地址推荐用嵌套结构

比如：

```
GET /books/1003/catalog
```

### 3.4 使用正确的HTTP Status Code表示访问状态

HTTP状态可以参考：[https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html。](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html%E3%80%82)

### 3.5 使用HTTPS协议

API与用户的通信协议总是使用HTTPS协议。

### 3.6 专有域名

应该尽量将API部署在专用域名之下。

```
 https://api.example.com
```

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

```
https://example.org/api/
```

> 参考：
>
> [http://www.ruanyifeng.com/blog/2014/05/restful\_api.html](http://www.ruanyifeng.com/blog/2014/05/restful_api.html)
>
> [http://www.ruanyifeng.com/blog/2011/09/restful.html](http://www.ruanyifeng.com/blog/2011/09/restful.html)
>
> [https://blog.csdn.net/chenxiaochan/article/details/73716617](https://blog.csdn.net/chenxiaochan/article/details/73716617)
>
> [https://www.zhihu.com/question/28557115?utm\_source=wechat\_search\&utm\_medium=organic](https://www.zhihu.com/question/28557115?utm_source=wechat_search\&utm_medium=organic)
