API设计规范

注:本文最早整理于2016年11月份,现在看来觉得仍有一些参考意义,故转帖到个人博客以备忘。

要求

在本文档中,使用的关键字会以中文+括号包含的关键字英文表示:必须(MUST)。关键字”MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”被定义在rfc2119中。

前言

越来越多的WEB程序使用JSON作为API的一种数据格式进行交互。本文档的目标是使API设计风格保持一致,容易被理解和维护。一个优秀的API,应该是在其生命周期内能够持续提供稳定、易用、受信任的服务,并且在API的生命周期结束时能让其平滑的消亡。

API的开发过程实际上就是一个沟通交流的过程,沟通的双方就是API的设计者(RD)和API的使用者(FE)。

URL的设计

你应该花一些时间来设计一下你的URL地址结构

结构

[强制] 全部使用小写字母拼写URL
// good
http://www.host.com/api/v1/users?orderby=name

// bad
http://www.host.com/API/V1/users?orderBy=name
[强制] 使用破折号 –
// good
http://www.host.com/api/v1/user-info

// bad
http://www.host.com/api/v1/user_info
[建议] 接口url应当使用简短的、完整的并且是大家都熟悉的单词。

HTTP响应头

[强制] status

http响应的status 必须(MUST) 为200。通常JSON数据被用于通过XMLHttpRequest对象访问,通过javascript进行处理。返回错误的状态码可能导致错误不被响应,数据不被处理。

参考:List_of_HTTP_status_codes

[建议] Content-Type

Content-Type字段定义了响应体的类型。一般情况下,浏览器会根据该类型对内容进行正确的处理。对于传输JSON数据的响应,Content-Type 推荐(RECOMMENDED) 设置为”text/javascript”或”text/plain”。 避免(MUST NOT) 将Context-Type设置为text/html,否则可能导致安全问题。

Content-Type中可以指定字符集。通常 需要(SHOULD) 明确指定一个字符集。如果是通过XMLHTTPRequest请求的数据,并且字符编码为UTF-8时,可以不指定字符集。

text/javascript;charset=UTF-8

API返回结果的设计

接口返回的数据结果 必须(MUST) 是一个JSON Object。该Object可能包含3个字段:code,msg,data。

// 框架级字段 code msg data

{
    code: 0,
    msg: 'done',
    data: {
        xxx: '123'
    }
}

code

code 字段被设计为业务自定义的状态码必须(MUST) 是一个不小于0的JSON Number整数,表示请求的状态。这个字段 可以(SHOULD) 被省略,省略时和为0时表示同一含义。

解释:

是否要在API里面自定义业务状态码,非常具有争议,因为Http请求本身已经有了完备的状态码,再定义一套状态码直观上感受却是不对劲,但在实际开发中,可能由于用户未登录、登录过期而有不同的返回结果和处理方式,所以还是保留了code字段。

状态码的定义也最好有一套规范,如按照用户相关、授权相关、各种业务,做简单的分类:

// 授权相关
1001: 无权限访问
1002: access_token过期
1003: unique_token无效
...

// 用户相关
2001: 未登录
2002: 用户信息错误
2003: 用户不存在

// 业务1
3001: 业务1XXX
3002: 业务1XXX

// ...

msg

msg 字段被设计为 本次请求的业务、状态描述信息,主要用于调试、测试、回显给用户等。

示例:
“done”、”success”、”用户ID参数错误” 等

data

data 字段被设计为 本次接口请求的业务数据,其值为对象(字典)或数组均可以,根据业务而定。

如请求的是键值对信息,就可以是对象

data: {
    uid: 123,
    name: 'foo',
    age: 29,
    sex: 1
}

如果请求的是列表数据,就可以是数组

data: [
    {
        uid: 123,
        name: 'foo',
        age: 29,
        sex: 1
    }
    ... // 省略号 伪代码
]

示例

下面给出了一个获取站点用户列表的接口设计规范

URL

/api/v1/users

接受参数
{
    orderby: 'name', // 根据name字段进行排序
    ordertype: 'asc' // 排序方式,倒序 还是 正序
}
返回参数
{
    code: 0,
    msg: 'success',
    data: {
        userList: [
            {
                uid: 123,
                name: 'foo',
                age: '29',
                sex: 1,
                birthday: '1987-5-22'
            },
            ... // 省略号,表示扔存在多个跟上结构相同的对象
        ]
    }
}

参考

这篇文章目前没有评论

Leave a Reply

(必填项)

(必填项)

(可选)