RESTful API规范

Posted 2021-01-05 在这里, 意淫和实干都值得尊重

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了RESTful API规范相关的知识，希望对你有一定的参考价值。

RESTful 规范指南:

1. HTTP 协议

API 与用户的通信协议, 总是使用 HTTPS 协议

2. 域名:


# 子域名方式:(解决跨域的问题)
    www.baidu.com
    api.baidu.com
# 存在跨域的风险
    
    
# =========================================
# URL 方式:
    www.baidu.com
    www.baidu.com/api/

3. 版本:


URL  如: https://api.baidu.com/v1/   
# 一般情况下都放在 url 上
请求头:                           跨域时, 引发发送多次请求

4. 路径

视网络上的一切都为资源, 均使用名词表示(可使用复数)


https://api.baidu.com/v1/zoos
https://api.baidu.com/v1/animals
https://api.baidu.com/v1/employees

5. method


GET:     从服务器取出资源(一项或多项)
POST:    在服务器新建一个资源
PUT:     在服务器更新资源( 客户端提供改变后的完整资源 )
PATCH:   在服务器更新资源( 客户端提供改变的属性 )
DELETE:  在服务器删除资源

6. 过滤:

通过在 URL 上传参的形式传递搜索条件


https://api.baidu.com/v1/zoos?limit=10      : 指定返回记录的数量
https://api.baidu.com/v1/zoos?offset=10     : 指定返回记录的开始位置
https://api.baidu.com/v1/zoos?page=2&per_page=100  : 指定第几页, 以及每页的记录数
https://api.baidu.com/v1/zoos?sortby=name&order=asc    : 指定返回结果按照那个属性排序, 以及排序顺序
https://api.baidu.com/v1/zoos?animal_type_id = 1        : 指定筛选条件

7. 状态码:

常用状态码:


200 – OK – 一切正常 
201 – OK – 新资源已经被创建 
204 – OK – 资源删除成功
304 – 没有变化，客户端可以使用缓存数据
400 – Bad Request – 调用不合法，确切的错误应该在error payload中描述，例如：“JSON 不合法 ” 
401 – 未认证，调用需要用户通过认证 
403 – 不允许的，服务端正常解析和请求，但是调用被回绝或者不被允许 
404 – 未找到，指定的资源不存在 
422 – 不可指定的请求体 – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。
500 – Internal Server Error – 标准服务端错误，API开发人员应该尽量避开这种错误

状态码和 code 结合使用
全部状态码:


RESTful API规范
 通俗易懂的 RESTful API 设计规范
 Python    Restful API设计规范
 RESTful 接口设计规范
 RESTful API规范
 RESTful API规范