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根目录发送请求返回功效的文档