[点晴永久免费OA]RESTful API设计规范
当前位置：点晴教程→点晴OA办公管理信息系统
→『 经验分享&问题答疑 』
该仓库整理了目前比较流行的 Table of Contents
关于「能愿动词」的使用为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下：
参见：RFC 2119 Protocol客户端在通过 API Root URL
如果你的应用很庞大或者你预计它将会变的很庞大，那 Versioning所有的 目前比较常见的两种版本号形式： 在 URL 中嵌入版本编号api.example.com/v1/* 这种做法是版本号直观、易于调试；另一种做法是，将版本号放在 通过媒体类型来指定版本信息Accept: application/vnd.example.com.v1+json 其中
后面几个参数依次为应用名称（一般为应用域名）、版本号、期望的返回格式。 至于具体把版本号放在什么地方，这个问题一直存在很大的争议，但由于我们大多数时间都在使用 Endpoints端点就是指向特定资源或资源集合的
至于 URL 是否必须使用连字符（ 来看一个反例
再来看一个正列
HTTP 动词对于资源的具体操作类型，由
其中 1 删除资源 针对每一个端点来说，下面列出所有可行的
超出 Filtering如果记录数量很多，服务器不可能都将它们返回给用户。API
所有 分页参数 经常使用的、复杂的查询 GET /trades?status=closed&sort=sortby=name&order=asc
# 可为其定制快捷方式
GET /trades/recently_closedAuthentication
Oauth 的端点设计示列
客户端在获得 {
"access_token": "token....",
"token_type": "Bearer",
"expires_in": 3600
}客户端在请求需要认证的 Authorization: Bearer token... 当超过指定的秒数后， HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_token"
}Laravel 开发中， Response所有的 HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": 0,
"msg": "success",
"data": {
"username": "username"
}
}或 HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": -1,
"msg": "该活动不存在",
}下表列举了常见的
只有来自客户端的请求被正确的处理后才能返回 必须强调的是，所有 1、将错误详细放入 X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication2、直接放入响应实体中； HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive
{"error_code":40100,"message":"Unauthorized"}考虑到易读性和客户端的易处理性，我们 {
"message": "您查找的资源不存在",
"error_code": 404001
}其中错误码（ HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:15:52 GMT
Connection: keep-alive
{"error_code":429001,"message":"你操作太频繁了"}HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:19:27 GMT
Connection: keep-alive
{"error_code":403002,"message":"用户已禁用"}
{
"message": "直接展示给终端用户的错误信息",
"error_code": "业务错误码",
"error": "供开发者查看的错误信息",
"debug": [
"错误堆栈，必须开启 debug 才存在"
]
}下面详细列举了各种情况 API 的返回说明。 200 ok
错误示例： HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"user": {
"id":1,
"nickname":"fwest",
"username": "example"
}
}正确示例： 1、获取单个资源详情 {
"id": 1,
"username": "godruoyi",
"age": 88,
}2、获取资源集合 [
{
"id": 1,
"username": "godruoyi",
"age": 88,
},
{
"id": 2,
"username": "foo",
"age": 88,
}
]3、额外的媒体信息 {
"data": [
{
"id": 1,
"avatar": "https://lorempixel.com/640/480/?32556",
"nickname": "fwest",
"last_logined_time": "2018-05-29 04:56:43",
"has_registed": true
},
{
"id": 2,
"avatar": "https://lorempixel.com/640/480/?86144",
"nickname": "zschowalter",
"last_logined_time": "2018-06-16 15:18:34",
"has_registed": true
}
],
"meta": {
"pagination": {
"total": 101,
"count": 2,
"per_page": 2,
"current_page": 1,
"total_pages": 51,
"links": {
"next": "http://api.example.com?page=2"
}
}
}
}其中，分页和其他额外的媒体信息，必须放到 201 created当服务器创建数据成功时，
等，都可以返回 HTTP/1.1 201 created
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:13:40 GMT
Connection: keep-alive
{
"id": 1,
"avatar": "https:\/\/lorempixel.com\/640\/480\/?32556",
"nickname": "fwest",
"last_logined_time": "2018-05-29 04:56:43",
"created_at": "2018-06-16 17:55:55",
"updated_at": "2018-06-16 17:55:55"
}也可以返回一个响应实体为空的 HTTP/1.1 201 created
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:12:20 GMT
Connection: keep-alive这里我们 202 Accepted该状态码表示服务器已经接受到了来自客户端的请求，但还未开始处理。常用短信发送、邮件通知、模板消息推送等这类很耗时需要队列支持的场景中； 返回该状态码时，响应实体 HTTP/1.1 202 Accepted Server: nginx/1.11.9 Content-Type: text/html; charset=UTF-8 Transfer-Encoding: chunked Date: Sun, 24 Jun 2018 09:25:15 GMT Connection: keep-alive 204 No Content该状态码表示响应实体不包含任何数据，其中：
HTTP/1.1 204 No Content
Server: nginx/1.11.9
Date: Sun, 24 Jun 2018 09:29:12 GMT
Connection: keep-alive3xx 重定向所有 HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 09:41:50 GMT
Location: https://example.com
Connection: keep-alive
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<meta http-equiv="refresh" content="0;url=https://example.com" />
<title>Redirecting to https://example.com</title>
</head>
<body>
Redirecting to <a href="https://example.com">https://example.com</a>.
</body>
</html>所有 HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:52:50 GMT
Location: https://godruoyi.com
Connection: keep-alive400 Bad Request由于明显的客户端错误（例如，请求语法格式错误、无效的请求、无效的签名等），服务器 当服务器无法从其他 4xx 类型的状态码中找出合适的来表示错误类型时，都 HTTP/1.1 400 Bad Request
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:22:36 GMT
Connection: keep-alive
{"error_code":40000,"message":"无效的签名"}401 Unauthorized该状态码表示当前请求需要身份认证，以下情况都
客户端在收到 HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
WWW-Authenticate: JWTAuth
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:17:02 GMT
Connection: keep-alive
{"message":"Token Signature could not be verified.","error_code": "40100"}403 Forbidden该状态码可以简单的理解为没有权限访问该请求，服务器收到请求但拒绝提供服务。 如当普通用户请求操作管理员用户时， HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:05:34 GMT
Connection: keep-alive
{"error_code":40301,"message":"权限不足"}404 Not Found该状态码表示用户请求的资源不存在，如
都 405 Method Not Allowed当客户端使用的 如客户端调用了 该响应 HTTP/1.1 405 Method Not Allowed
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Allow: GET, HEAD
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:30:57 GMT
Connection: keep-alive
{"message":"405 Method Not Allowed","error_code": 40500}406 Not Acceptable
Http 协议一般通过请求首部的 Accept 来指定数据格式 408 Request Timeout客户端请求超时时 409 Confilct该状态码表示因为请求存在冲突无法处理。如通过手机号码提供注册功能的 HTTP/1.1 409 Conflict
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:19:04 GMT
Connection: keep-alive
{"error_code":40900,"message":"手机号已存在"}410 Gone和 413 Request Entity Too Large该状态码表示服务器拒绝处理当前请求，因为该请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。 此种情况下，服务器可以关闭连接以免客户端继续发送此请求。 如果这个状况是临时的，服务器 414 Request-URI Too Long该状态码表示请求的 415 Unsupported Media Type通常表示服务器不支持客户端请求首部 该状态码也可用于如：只允许上传图片格式的文件，但是客户端提交媒体文件非法或不是图片类型，这时 HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:09:40 GMT
Connection: keep-alive
{"error_code":41500,"message":"不允许上传的图片格式"}429 Too Many Requests该状态码表示用户请求次数超过允许范围。如 X-RateLimit-Limit: 10 请求速率（由应用设定，其单位一般为小时/分钟等，这里是 10次/5分钟） X-RateLimit-Remaining: 0 当前剩余的请求数量 X-RateLimit-Reset: 1529839462 重置时间 Retry-After: 120 下一次访问应该等待的时间（秒） 列子 HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive
{"message":"You have exceeded your rate limit.","error_code":42900}
500 Internal Server Error该状态码 503 Service Unavailable该状态码表示服务器暂时处理不可用状态，当服务器需要维护或第三方 HTTP/1.1 503 Service Unavailable
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:56:20 GMT
Retry-After: 60
Connection: keep-alive
{"error_code":50300,"message":"服务维护中"}其他 版权声明版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证） 建议参考Principles of good RESTful API Design（译） LICENSEMIT License Copyright (c) 2018 godruoyi Permission is hereby granted, free of charge, to any person obtaining a copy The above copyright notice and this permission notice shall be included in all THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 该文章在 2022/4/18 18:07:11 编辑过 |
关键字查询
相关文章
正在查询... 
|
400 186 1886
