一、协议
API与用户的通信协议==>HTTPs协议
二、域名
- 专用域名：https//api.ex.com
- 主域名（api简单）：https//ex.com/api/
三、版本
版本号放入URL：https://api.ex.com/v1/
版本号放入HTTP头信息：不如URL直观方便
四、路径(endpoint)
表示API的具体网址
网址代表资源==只能用名词==名词与数据库表格名对应-->表为集合所以名词应为复述
案例：动物园（zoo）的api，包括动物和雇员信息
//路径设计
https://api.ex.com/v1/zoos https://api.ex.com/v1/animals https://api.ex.com/v1/employees
五、HTTP动词
表示对资源的操作类型
- 常用HTTP动词
GET（SELECT）//从服务器取出资源（一项或多项） POST（CREATE）//在服务器新建资源 PUT（UPDATE）//在服务器更新资源（客户端提供改变后的完整资源） PATCH（UPDATE）//在服务器更新资源（客户端提供改变的属性） DELETE（DELETE）//从服务器删除资源）
- 不常用HTTP动词
HEAD //获取资源的元数据 OPTIONS //获取信息，客户端可更改资源的哪些属性
- 实例
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 //删除某个指定动物园的指定动物
六、过滤信息（Filtering）
记录数量过多时API提供参数返回过滤结果
常见参数
?limit=10 //指定返回记录的数量 ?offset=10 //指定返回记录的开始位置 ?page=2&per_page=100 //指定第几页，及每页记录数 ?sortby=name&order=asc //指定返回结果按照哪个属性排序，以及排序顺序 ?animal_type_id=1 //指定筛选条件
ps:参数设计允许API路径和URL参数有重复
- GET /zoo/ID/animals 等价于 GET /animals?zoo_id=ID
七、状态码（Status Codes）
服务器向用户返回状态码和提示信息
常见案例[方括号内为该状态码对应的HTTP动词]
200 OK - [GET] //服务器成功返回用户请求的数据，幂等操作 201 CREATED - [POST/PUT/PATCH] //用户新建或修改数据成功 202 Accepted - [*] //一请求已进入后台排队（异步任务） 204 NO CONTENT - [DELETE] //用户删除数据成功 400 INVALID REQUEST - [POST/PUT/PATCH] //用户请求有错误，服务器没有新建和修改，幂等操作 401 Unauthorized - [*] //用户无权限（令牌、用户名、密码错误） 403 Forbidden - [*] //用户得到授权但访问禁止 404 NOT FOUND - [*] //用户请求的记录不存在，服务器无操作，幂等操作 406 Not Acceptable - [GET] //用户请求的格式不可得，如没有JSON格式只有XML 410 Gone - [GET] //用户请求资源被永久删除，无法再得 422 Unprocesable entity - [POST/PUT/PATCH] //创建一个对象发生验证错误 500 INTERNAL SERVER ERROR - [*] //服务器发生错误，不能判断请求是否成功
八、错误处理（Error handling）
状态码为4XX时候向用户返回出错信息
该信息将error为键名，出错信息为键值
{ error:"Invalid API key/无效的API密钥" }
九、返回结果
对不同操作的返回结果规范
GET /collection //返回资源对象的列表（数组） GET /collection/resource //返回单个资源对象 POST /collection //返回新生成的资源对象 PUT /collection/resource //返回完整的资源对象 PATCH /collection/resource //返回完整的资源对象 DELETE /collection/resource //返回一个空文档
十、Hypermedia API （超媒体）
返回结果提供指向其他api方法的链接，使用户无需查文档
案例：用户向api.example.com根目录发送请求返回结果的文档
{ "link:"{ "rel":"collection https://www.ex.com/zoos", "href": "https://api.example.com/zoos", "title": "List of zoos", "type": "application/vnd.yourformat+json" } }
文档说明：
- link属性，用户读取该属性知道下一步做什么
- rel：该api与当前网址的关系
- href：API路径
- title :API标题
- type:返回类型
案例：GitHub-API
// 访问api.github.com 返回所有可用api的网址列表 { "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations", // ... } //从列表可看出想获取当前用户信息应访问 https://api.github.com/user //获取结果：提示信息及文档网址 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }
十一、其他
- API的身份认证应使用OAuth2.0框架
- 服务器返回数据格式最好用JSON
文章学习来源 http://www.ruanyifeng.com/blog/2014/05/restful_api.html