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值说明

样例：

​ 请求参数 uid 1

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

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

10-django——RESTful API 之序列化