API Application Program Interface简称 接口
一些预先定义的函数 WEB Android IOS端
列:WEB https://api.qq.com/user/getUserList?from=web
列:安卓端 https://api.qq.com/user/getUserList?from=android
REST 是 "Representational state transfer"缩写 表现性状态转换
在RESTful中一切都被认为是资源,每个资源有对应的应用URL标识
处理资源使用GET\\POST\\DELETE等方法操作实现创建 读取 修改 删除的操作
客服端通过四个HTTP动词,对服务器端资源进行操作,实现"表现层状态转换"
## 1协议
REST API与用户的通信协议,总是使用HTTP协议.
## 2域名
部署在专用域名下 https://api.example.com
如果确定API很简单,不会进一步的扩展可以放在主域名下操作 https://example.com/api/
## 3版本
应该讲API的版本号放入URL https://api.example.com/version/
还有一种做法是将版本号放入HTTP头信息中,但不如放入URL方便和直观
## 4路劲
又称"终点"(endpoint),表示API的具体网址
API中的名词都应该用负数 比如animals employees
## 5http动词
```
POST(CREATE):在服务器新建一个资源
DELETE(DELETE):从服务器删除资源
PUT(UPDATE):在服务器更新资源(客服端提供改变后的完整资源)
GET(SELECT):从服务器取出资源(一项或多项)
```
## 6过滤信息
```
如果记录过多服务器不可能都将他们返回客户,API应该提供参数,过滤返回结果.
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置
?page=2&per_page=100;指定第几页,以及每页的记录数
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
?animal_type_id=1:指定筛选条件
```
## 7状态码
```
200 OK-[GET]
201 CREATED -[POST/PUT/PATCH]:用户新建或修改数据成功
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功
400 INVALID REQUST - [POST/PUT/PATCH]:用户发出请求有错误,服务器没有进行新建或修改数据的操作
401 Unauthorized - [*]:表示用户没有权限(令牌 用户名 密码错误)
403 Forbidden - [*]:表示用户得到授权(与401错误相对),但是访问是禁止的
404 NOT FOUND - [*]:用户发出请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的
406 NOT Acceptabel - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)
410 Gone - [GET]:用户请求的资源被永久删除,且不会在得到的
422 Unprocesable entity -[POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发生的请求是否成功
```
## 8错误处理
```
产生错误就像用户返回出错误信息,error作为键名,出错信息作为键值即可
{
error:"Invalid API key"
}
```
## 9 返回结果
```
GET /collection:返回资源对象的列表
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档
```
