RESTful API 接口设计规范总结

推荐：

Restful接口规范

本文总结api接口开发中的一些规范，避免在开发过程中出现‘选择性’的问题。

描述	样例	备注
API 的根入口点应尽可能保持足够简单	① api.example.com/* ②example.com/api/*
在 URL 中嵌入版本编号	api.example.com/v1/*
URL 的命名规范： ①命名必须全部小写；②资源路由的命名必须是名词，并且是复数形式；③必须 优先使用 Restful 类型的 URL；④不能出现 -，必须 用下划线 _ 代替；⑤必须 是易读的；⑥一定不可 暴露服务器架构	https://api.example.com/zoos https://api.example.com/animals https://api.example.com/zoos/{zoo}/animals https://api.example.com/animal_types https://api.example.com/employees
请求方式：①删除资源 必须 用 DELETE 方法；②创建新的资源 必须 使用 POST 方法；③更新资源 应该 使用 PUT 方法；④获取资源信息 必须 使用 GET 方法；	-	开发中常以：get请求只是用来查询数据；post请求是用来增删改数据
一些通用的参数名称约定	①limit=1 指定返回记录的数量； ②offset=10：指定返回记录的开始位置；③page=2&per_page=100：指定第几页，以及每页的记录数；
使用Access Token进行身份认证	应该 使用 OAuth2.0 的方式为 API 调用者提供登录认证。必须 先通过登录接口获取 Access Token 后再通过该 token 调用需要身份认证的 API。	也可以采用session的登录机制

Response标准格式：

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "code": 0,
    "msg": "success",
    "data": {
        "username": "username"
    }
}
or
{
    "code": -1,
    "msg": "该活动不存在",
}

常见的状态返回码：

状态码	描述
1xx	代表请求已被接受，需要继续处理
2xx	请求已成功，请求所希望的响应头或数据体将随此响应返回
3xx	重定向
4xx	客户端原因引起的错误
5xx	服务端原因引起的错误
注：
1、只有来自客户端的请求被正确的处理后才能返回 2xx 的响应，所以当 API 返回 2xx 类型的状态码时，前端 必须 认定该请求已处理成功。
2、所有 API 一定不可 返回 1xx 类型的状态码。
3、所有 API 一定不可 返回 3xx 类型的状态码。
4、状态码从100000开始，基本能满足大部分的项目需求,而且可读性强。
例如 ：
状态码	说明
–	–
0	请求成功
45****	实际业务中的状态码
400000	无效的签名
404001	您查找的资源不存在
403001	权限不足
403002	用户已禁用
405001	请求方法不被服务器允许
406001	不支持客户端指定的数据格式
408001	客户端请求超时
409001	状态码表示因为请求存在冲突无法处理，如：手机号已存在
410001	所请求的资源已不存在，并且未来也不会存在
413001	服务器拒绝处理当前请求，提交的实体数据大小超过了服务器愿意或者能够处理的范围
414001	请求的 URI 长度超过了服务器能够解释的长度，因此服务器拒绝对该请求提供服务。
415001	通常表示服务器不支持客户端请求首部 Content-Type 指定的数据格式。
429001	你操作太频繁了（表示用户请求次数超过允许范围）
500001	服务器出错
503001	服务器暂时处于不可用状态，当服务器需要维护或第三方 API 请求超时 / 不可达时
503505	服务器不支持请求中所用的 HTTP 协议版本

参考：
RESTful API 设计规范