10分钟带你理解restfulAPI

   从what，why，how几个方面来讲解restfulAPI。在解读restfulAPI之前，先说一说什么是rest，rest并不是单纯的一个单词，而是Representational State Transfer的缩写， 直接翻译：表现层状态转移，如果不懂，没关系，因为他省略了最主要的主语，目前我认为rest最好的中文翻译是“资源在网络中以某种表现形式进行状态转移”。下面对每个单词做一个简单的解释，有利于我们更好的理解rest。

Resource：资源，即数据。database中存储的信息；
Representational：某种表现形式，比如用JSON，XML，JPEG等；
State Transfer：状态变化。通过HTTP动词实现。post，delete，put，get。

 

   了解了rest，接下来我们来聊一聊restfulAPI，刚刚讲到的rest只是描述在网络中client和server的一种交互形式；rest本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）；
   Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。比如：http://api.xv.com/v1/orders: 获取订单列表; api.xv.com/v1/friends: 获取好友列表;
    用HTTP协议里的动词来实现资源的添加，修改，删除等操作。即通过HTTP动词来实现资源的状态扭转，GET 用来获取资源，POST 用来新建资源，PUT 用来更新资源，DELETE 用来删除资源。

比如：DELETE http://http://api.xv.com/v1/orders 删除订单 ，POST http://api.qc.com/v1/friends: 添加好友

  
    对restfulAPI有了简单的认识，那么我们为什么要使用rest风格的API设计呢？我们都知道早期的网页都是前端后端融在一起的，比如之前的PHP，JSP等。在之前的桌面时代问题不大，但是近年来移动互联网的发展，各种类型的Client层出不穷，RESTful可以通过一套统一的接口为 Web，iOS和Android提供服务。另外对于广大平台来说，比如Facebook platform，微博开放平台，微信公共平台等，它们不需要有显式的前端，只需要一套提供服务的接口，于是RESTful更是它们最好的选择。

   

如何来实现rest风格API的设计
1. URL root:路径中，用名词来代表要访问的资源
如上面提到的orders订单，frieds朋友
2. API versioning:API的版本编号，如v1，v2
可以放在URL里面，也可以用HTTP的header：
/api/v1/
3. URI使用名词而不是动词，且推荐用复数。
GET /products : 获取所有商品
POST /products : 新建商品
GET /products/4 : 获取id为4的商品
PATCH/PUT /products/4 : 更新商品为4的商品
4. 保证 HEAD 和 GET 方法是安全的，不会对资源状态有所改变（污染）。比如严格杜绝如下情况：
GET /deleteProduct?id=1
5. 资源的地址推荐用嵌套结构。比如：
GET /friends/10375923/profile
UPDATE /profile/primaryAddress/city
6. 警惕返回结果的大小。如果过大，及时进行分页（pagination）或者加入限制（limit）。HTTP协议支持分页（Pagination）操作，在Header中使用 Link 即可。
7. 使用正确的HTTP Status Code表示访问状态
8. 在返回结果用明确易懂的文本（返回的错误适当的加入注释）
9. 关于安全：自己的接口就用https，加上一个key做一次hash放在最后即可。考虑到国情，HTTPS在无线网络里不稳定，可以使用Application Level的加密手段把整个HTTP的payload加密。有兴趣的朋友可以用手机连上电脑的共享Wi-Fi，然后用Charles监听微信的网络请求（发照片或者刷朋友圈）。

     当拥有了一套成熟的API之后，各个终端的实现
    Server统一提供一套RESTful API，web+ios+android作为同等公民调用API。各端发展到现在，都有一套比较成熟的框架来帮开发者事半功倍。