RESTful API的理解

RESTful API

目前的异步加载横行的时候，异步请求已经遍地都是，而规定请求接口的时候，若是不能有很好的风格的话，不少时候会让开发者误解，一个好的API接口 设计须要注意如下：

1. 参数职责单一
2. 意图清晰，便于开发者调用
3. 易于访问者输入

看是可是真的设计的时候常常会设计出不规范 的接口，

REST原则

REST 即Representational State Transfer的缩写。它的理论比较抽象不太具体，理解它主要在于理解这些概念：资源、表现层、状态转换。
基于REST原则设计的API，通常称为 RESTFul API，须要遵照如下这些原则。

1. URL描述的是一个特定资源。所以描述须要名词，不能出现动词。由于动词描述的再也不是资源自己，而是行为
2. 利用HTTP请求的动词表示对于资源操做的行为

同时，对于URL的设计通常还有约定俗成的如下补充。

1. 对于资源的描述的名词应该是层级嵌套的方式，好比 /company/department/projects。经过这种对于信息层级描述的方式，更利于实体的抽象，以及增长客户端与服务器端开发人员对于整个系统模块认知的一致性
2. 路径终点的命名考虑用复数形式，好比 /books。通常一个URL路径表示的资源会映射为数据库一系列表的记录的集合，所以使用复数更直观

实践设计

实际设计restful api时的注意点包括如下：

1. 尽可能使用https协议
2. 若是接口是公用且会被扩展时，应该考虑放在专有域名下，https://api.baidu.com
3. 因为api会在业务中不断地迭代，因此最好是带上版本，https://api.baidu.com/v2/
4. 最后接口路径应该尽可能使用集合，也就是复数形式，https://api.baidu.com/v2/books

5. 操做类接口应该注意使用对应的动词来操做

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

6. 参数，使用参数来进行筛选，?page=2&per_page=100：指定第几页，以及每页的记录数。
7. 返回结果，结果应该包括多种状况，异常、错误信息、正确结果{status:'ok',massage:'ok',data:{data:1}}
8. 目前而言最好使用JSON格式传输数据。

参考：efe的restful理解，阮一峰restful api