Django—— restful 设计风格

RESTful Api设计风格

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

域名：应该尽量将 API 部署在专用域名之下，如果确定 API 很简单，不会有进一步的扩展，可以考虑放在主域名之下。

版本：

应该将 API 的版本放在 URL 中：https://www.sunck.wang/api/v1.0
将版本号放在 HTTP 头信息中：https://www.sunck.wang/students
路径：表示 API 的具体网址，每个网址代表一种资源，所以网址中不能有动词，只能有名词，并且所用的名词往往与数据库的表名对应。数据库中的表示记录同种数据的集合，所以 API 中的名词也应该使用复数。

获取所有学生：

https://www.sunck.wang/api/v1... 错误写法
https://www.sunck.wang/api/v1... 正确写法

使用正确的 HTTP 请求方法

例子

过滤信息

如果资源数较多，服务器不能将所有数据一次全部返回给客户端，API 应该提供参数，过滤返回结果

例子

注意：参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复

状态码

服务器向客户端返回的状态码和提示信息

错误处理

如果错误码是4xx，就应该向用户返回错误信息，一般来说，返回的信息中将 error 作为键名，出错的信息作为键值即可

{
    error:'Invalid API KEY',
}

响应结果

针对不同的操作，服务器向用户返回结果应该符合规范

使用链接相关的资源

返回结果中提供了链接，链向了其他的 API 方法，使得用户不查看文档，也知道下一步应该做什么

示例

{
    link:"www.sunck.wang/grades/"
}
{
    "link":{
        "rel":"collection www.sunck.wang/index/",
        "href":"www.sunck.wang/grades/",
        "title":"List of Grades",
        "type":"application/json",
    }
}

键

rel：表示这个 API 与当前网址的关系

href：表示 API 路径

title：表示 API 的标题

type：表示返回的类型

其他：服务器返回的数据尽量使用 JSON 格式，避免使用 XML 格式

API 文档规范要求

一、写明该接口的功能是什么

二、请求的 URL 是什么

三、请求方式是什么（POST、GET、 DELETE、PUT、 PATCH等）

四、参数是什么，此处还需说明你的参数名、参数类型、是否必填、参数的简单解释

五、请求成功时的响应内容（实际开发中，要与前端同事沟通使用什么样的数据结构），并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）

六、请求失败时的响应内容，并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）包括单独的对错误码的说明

七、请求样例（返回结果部分要包括成功的情况和失败的情况）

八、最好写上文档的编写人和编写时间（可不写）

Demo：

功能：获取某人的下属
URL：”people/api/v1/ subordinate”

请求参数说明：

请求成功参数说明

data 内的响应参数说明

请求失败参数说明

code值说明

Code 说明
1 成功
2 该人已经离职
3 请求参数不完整
4 参数类型错误
样例：

请求参数 uid 1

# 请求成功样例
{
    ,
    'msg': 'ok',
    'data':[
        {
        ,
        'name': 'Tom',
        'position': '教师'
        },
        {
        ,
        'name’: 'Lucy',
        'position': '助教'
        }
    ]
}

# 请求失败样例
    {
        ,
        'msg': '该人已离职'
}

作者：rottengeek
原文链接：http://t.cn/RgC0MIP

第 19 期Python实战班正在火热招生中
第 8 期自动化运维班正在招生中
第4 期 golang 正在招生中

详情扫码咨询

免费视频戳戳戳!