一、 摘要(Abstract)
RESTful API 已经非常成熟,也得到了大家的认可。我们按照 Richardson Maturity Model 对 REST 评价的模型,规范基于 level2 来设计
二、版本(Versioning)
API的版本号放入URL。例如:
https://api.jiuyescm.com/v1/
https://api.jiuyescm.com/v1.2/
三、资源、路径(Endpoint)
路径,API的具体地址。在REST中,每个地址都代表一个具体的资源(Resource
)约定如下:
- 路径仅表示资源的路径(位置),尽量不要有actions操作(一些特殊的
actions
操作除外) - 路径以 复数(名词) 进行命名资源,不管返回单个或者多个资源。
- 使用 小写字母、数字以及下划线(“_”) 。(下划线是为了区分多个单词,如user_name)
-
资源的路径从父到子依次如:
/{resource}/{resource_id}/{sub_resource}/{sub_resource_id}/{sub_resource_property}
-
使用
?
来进行资源的过滤、搜索以及分页等 -
使用版本号,且版本号在资源路径之前
-
优先使用内容协商来区分表述格式,而不是使用后缀来区分表述格式
-
应该放在一个专用的域名下,如:
http://api.jiuyescm.com
-
使用SSL
综上,一个API路径可能会是
https://api.domain.com/v1/{resource}/{resource_id}/{sub_resource}/{sub_resource_id}/{sub_resource_property}
https://api.domain.com /v1/{resource}?page=1&page_size=10
https://api.domain.com /v1/{resource}?name=xx&sortby=name&order=asc
四、操作(HTTP Actions)
用HTTP
动词(方法)表示对资源的具体操作。常用的HTTP
动词有:
GET(SELECT):从服务器取出资源(一项或多项)
POST(CREATE):在服务器新建一个资源
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)
DELETE(DELETE):从服务器删除资源
还有两个不常用的HTTP动词
HEAD:获取资源的元数据
OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的
下面是一些例子
GET /users:列出所有用户
POST /users:新建一个用户
GET /users/{user_id}:获取某个指定用户的信息
PUT /users/{user_id}:更新某个指定用户的信息(提供该用户的全部信息)
PATCH /users/{user_id}:更新某个指定用户的信息(提供该用户的部分信息)
DELETE /users/{user_id}:删除某个用户
GET /users/{user_id}/resources:列出某个指定用户的所有权限资源
DELETE /users/{user_id}/resources/{resources_id}:删除某个指定用户的指定权限资源
五、数据(Data Format)
数据是对资源的具体描述,分为请求数据和返回数据。约定如下:
- 查询,过滤条件使用query string,例如user?name=xxx
- Content body 仅仅用来传输数据
- 通过Content-Type指定请求与返回的数据格式。其中请求数据还要指定Accept。(我们暂时只使用Json)
- 数据应该拿来就能用,不应该还要进行转换操作
- 使用字符串(YYYY-MM-dd hh:mm:ss)格式表达时间字段,例如: 2017-02-20 16:00:00
- 数据采用UTF-8编码
- 返回的数据应该尽量简单,响应状态应该包含在响应头中
- 使用 小写字母、数字以及下划线(“_”) 描述字段,不使用大写描述字段(这个由于使用了一些开源的jar所以这个不强求,比如说pageinfo我们无法修改属性名称)
- 建议资源中的唯一标识命名为id(这个不强求,有的唯一标识名称确实比较复杂)
- 属性和字符串值必须使用双引号””(这个json转换默认规则)
- 建议对每个字段设置默认值(数组型可设置为[],字符串型可设置为””,数值可设置为0,对象可设置为{}),这一条是为了方便前端/客户端进行判断字段存不存在操作(这样json转换会自动转成相应的字符)
- POST操作应该返回新建的资源;PUT/PATCH操作返回更新后的完整的资源;DELETE返回一个空文档;GET返回资源数组或当个资源
- 为了方便以后的扩展兼容,如果返回的是数组,强烈建议用一个包含如items属性的对象进行包裹,如:
{"items":[{},{}]}
示例:
POST https://api.domain.com/v1/users
Request
headers:
Accept: application/json
Content-Type: application/json;charset=UTF-8
body:
{
"user_name": "ZhangSan",
"address": "ujfhysdfsdf",
"nick": "ZS"
}
Response
status: 201 Created
headers:
Content-Type: application/json;charset=UTF-8
body:
{
"requestId": sdfsdflkjoiusdf,
"code": "",
"message": "",
"items":
{
"id":"111",
"user_name": "HingKwan",
"address": "ujfhysdfsdf",
"nick": "ZS"
}
}
六、安全(Security)
调用限制
为了避免请求泛滥,给API设置速度限制很重要。入速度设置之后,可以在HTTP返回头上对返回的信息进行说明,下面是几个必须的返回头(依照twitter的命名规则)
X-Rate-Limit-Limit :当前时间段允许的并发请求数
X-Rate-Limit-Remaining:当前时间段保留的请求数
X-Rate-Limit-Reset:当前时间段剩余秒数
这个我们一般会在getway中实现
授权校验
RESTful API是无状态的也就是说用户请求的鉴权和cookie以及session无关,每一次请求都应该包含鉴权证明。 可以使用http请求头Authorization设置授权码; 必须使用User-Agent设置客户端信息, 无User-Agent请求头的请求应该被拒绝访问。具体的授权可以采用OAuth2,或者自己定义并实现相关的授权验证机制(基于token)。 这个我们一般会在getway中实现
错误
当API返回非2XX的HTTP响应时,应该采用统一的响应信息,格式如:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"code":"INVALID_ARGUMENT",
"message":"{error message}",
"request_id":"sdfsdfo8lkjsdf",
"items":[],
}
- HTTP Header Code:符合HTTP响应的状态码。详细见以下的“状态码”节
- code:用来表示某类错误不是具体错误,比如缺少参数等。是对HTTP Header Code的补充,开发团队可以根据自己的需要自己定义
- message:错误信息的摘要,应该是对用户处理错误有用的信息
- request_id:请求的id,方便开发定位发生错误的请求(可选)
- code的定义约定:
- 采用 大写字母命名,字母与字母之间用下划线(”_”) 隔开
- code应该用来定义错误类别,而非定义具体的某个错误。
- 缺少参数使用:MISSING_X
- 无效参数使用:INVALID_X
- 逻辑验证错误使用:VALIDATION_X
- 不存在使用:NO_FOUND_X
七、状态码(Status Codes)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
200 OK - [GET/PUT/PATCH/DELETE]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 Created - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 No Content - [DELETE]:用户删除数据成功。
304 Not Modified - HTTP缓存有效。
400 Invalid Request - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 Not Found - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
405 Method Not Allowed - [*]:该http方法不被允许。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
415 Unsupported Media Type - [*]:请求类型错误。
422 Unprocesable Entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
429 Too Many Request - [*]:请求过多。
500 Internal Server Error - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
503 Service Unavailable - [*]:服务当前无法处理请求。
八、异常规范(Exceptions)
- Controller中try catch住service的异常,再转换为restful中需要抛出的异常
try {
Long id = userService.save(vo);
vo.setId(id);
} catch(BizException e) {
throw new UnprocesableEntityException(ErrorCode.USER_NAME_EXIST.getCode(), ErrorCode.USER_NAME_EXIST.getMessage());
}
- Controller中抛出的异常必须使用spring-mvc-rest包中的异常类,不允许自定义异常,选择需要返回的httpStatus对应的异常
#403 [*]:表示得到授权(与401错误相对),但是访问是被禁止的。
com.jiuyescm.spring.mvc.rest.exception.ForbiddenException
#401 [GET]:用户请求的资源被永久删除,且不会再得到的。
com.jiuyescm.spring.mvc.rest.exception.GoneException
#400 [POST/PUT/PATCH]:用户发出的请求有错误(常用在请求必要的参数错误上),服务器没有进行新建或修改数据的操作,该操作是幂等的。
com.jiuyescm.spring.mvc.rest.exception.InvalidRequestException
#406 [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)或(请求参数需要数字,用户传入字符串)
com.jiuyescm.spring.mvc.rest.exception.NotAcceptableException
#404 [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
com.jiuyescm.spring.mvc.rest.exception.NotFoundException
#401 [*]:表示没有权限(令牌、用户名、密码错误,或任何资源没有权限)
com.jiuyescm.spring.mvc.rest.exception.UnauthorizedException
#422 [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
com.jiuyescm.spring.mvc.rest.exception.UnprocesableEntityException
- 抛出的异常中需要传入异常编码和异常信息,异常编码定义遵循上面 《安全中错误编码规范》
"MESSING_ID", "缺少参数:id"
"MESSING_NAME", "缺少参数:name"
"MESSING_ADDRESS", "缺少参数:address"
"USER_NAME_EXIST", "用户名已存在"
"USER_NOT_FOUND", "用户名不存在"
- 常用的错误编码、异常、httpStatus对应关系
"MESSING_ID", "缺少参数:id"、InvalidRequestException、400
"MESSING_NAME", "缺少参数:name"、InvalidRequestException、400
"MESSING_ADDRESS", "缺少参数:address"、InvalidRequestException、400
"USER_NAME_EXIST", "用户名已存在"、UnprocesableEntityException、422
"USER_NOT_FOUND", "用户名不存在"、NotFoundException、404
九、示例(Example)
采用user提供的示例代码
POST /users
Resource POST /v1/users
POST Parameters Endpoint requires:
Name | Type | Description |
---|---|---|
name | String | 用户名称 |
address | String | 用户住址 |
and accepts a few other parameters listed below.
Name | Type | Description |
---|---|---|
remark | String | 描述信息 |
Example
{
"name":"tuyir",
"address":"sdflkjsdf",
"remark":"sdfoiu"
}
Response Status-Code: 201 Created
{
"code": "",
"message": null,
"items": {
"id": 27,
"name": "tuyir",
"address": "sdflkjsdf",
"remark": "sdfoiu"
}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
Items | Objec | t 返回结果 |
id | Long | 唯一标识 |
name | String | 用户名称 |
address | String | 家庭住址 |
remark | String | 描述信息 |
Error response Status-Code: 400 Bad Request
{
"code": "MESSING_NAME",
"message": “缺少参数:name”,
"items": {}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
Items | Object | 返回结果 |
HTTP Error Codes
HTTP Status | Code | Description |
---|---|---|
400 | MESSING_NAME | 缺少参数:name |
400 | MESSING_ADDRESS | 缺少参数:address |
422 | USER_NAME_EXIST | 用户名已存在 |
500 | INTERNAL_SERVER_ERROR | 未知的错误 |
DELETE /users/{user_id}
Resource DELETE /v1/users/{user_id}
Path Parameters
Name | Type | Description |
---|---|---|
user_id | Long | 用户唯一标识 |
Query Parameters None
Example Request
curl –H ‘Content-Type: application/json’\
-X DELETE \
‘https://api.jiuyescm.com/v1/users/111’
Response Status-Code: 204 No Content
HTTP Error Codes
HTTP Status | Code | Description |
---|---|---|
400 | MESSING_ID | 缺少参数:id |
404 | USER_NOT_FOUND | 用户不存在 |
PUT /users
Resource PUT /v1/users
PUT Body Parameters Endpoint requires:
Name | Type | Description |
---|---|---|
user_id | Long | 用户唯一标识 |
user_name | String | 用户名称 |
address | String | 用户住址 |
and accepts a few other parameters listed below..
Name | Type | Description |
---|---|---|
remark | String | 描述信息 |
Example
{
"user_id": 12,
"name":"tuyir",
"address":"sdflkjsdf",
"remark":"sdfoiu"
}
Response Status-Code: 200 OK
{
"code": "",
"message": null,
"items": {
"id": 12,
"name": "tuyir",
"address": "sdflkjsdf",
"remark": "sdfoiu"
}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
Items | Object | 返回结果 |
id | Long | 唯一标识 |
name | String | 用户名称 |
address | String | 家庭住址 |
remark | String | 描述信息 |
Error response Status-Code: 400 Bad Request
{
"code": "MESSING_NAME",
"message": “缺少参数:name”,
"items": {}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
HTTP Error Codes
HTTP Status | Code | Description |
---|---|---|
code | String | 错误编码 |
400 | MESSING_ID | 缺少参数:id |
400 | MESSING_NAME | 缺少参数:name |
400 | MESSING_ADDRESS | 缺少参数:address |
422 | USER_NAME_EXIST | 用户名已存在 |
500 | INTERNAL_SERVER_ERROR | 未知的错误 |
GET /users/{user_id}
Resource GET /v1/users/{user_id}
Path Parameters
Name | Type | Description |
---|---|---|
user_id | Long | 用户唯一标识 |
Example Request
Curl –H 'Content-Type: application/json' \
'https://api.jiuyescm.com/v1/users/12'
Response Status-Code: 200 OK
{
"code": "",
"message": null,
"items": {
"id": 12,
"name": "tuyir",
"address": "sdflkjsdf",
"remark": "sdfoiu"
}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
Items | Object | 返回结果 |
id | String | 唯一标识 |
name | String | 用户名称 |
address | String | 家庭住址 |
remark | String | 描述信息 |
Error response Status-Code: 404 Bad Request
{
"code": " USER_NOT_FOUND",
"message": “用户不存在”,
"items": {}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
HTTP Error Codes
HTTP Status | Code | Description |
---|---|---|
400 | MESSING_ID | 缺少参数:id |
404 | USER_NOT_FOUND | 用户不存在 |
GET /users
Resource GET /v1/users
Query Parameters
Name | Type | Description |
---|---|---|
name | String | 根据用户名称进行查询 |
page | int | 第几页,不传入默认1 |
page_size | int | 每页返回多少条结果,不传入默认20 |
Example Request
Curl –H 'Content-Type: application/json' \
'https://api.jiuyescm.com/v1/users?name=xxx&page=1&page_size=20'
Response Status-Code: 200 Success
{
"code": "",
"message": "",
"items": {
"pageNum": 1,
"pageSize": 20,
"size": 17,
"startRow": 1,
"endRow": 17,
"total": 17,
"pages": 1,
"list": [
{
"id": 2,
"name": "ningyu1",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 3,
"name": "ningyu2",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 4,
"name": "ningyu3",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 5,
"name": "ningyu4",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 6,
"name": "ningyu5",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 7,
"name": "8888",
"address": "8888",
"remark": "8888"
},
{
"id": 8,
"name": "444",
"address": "444",
"remark": "444"
},
{
"id": 9,
"name": "ningyu7",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 12,
"name": "ningyu9",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 13,
"name": "ningyu10",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 17,
"name": "ningyu",
"address": "sdflkjsdf",
"remark": null
},
{
"id": 20,
"name": "9999",
"address": "sdflkjsdf",
"remark": null
},
{
"id": 23,
"name": "888",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 24,
"name": "222",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 25,
"name": "222444",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 26,
"name": "222444sdf",
"address": "sdflkjsdf",
"remark": "sdfoiu"
},
{
"id": 27,
"name": "tuyir",
"address": "sdflkjsdf",
"remark": "sdfoiu"
}
],
"firstPage": 1,
"prePage": 0,
"nextPage": 0,
"lastPage": 1,
"isFirstPage": true,
"isLastPage": true,
"hasPreviousPage": false,
"hasNextPage": false,
"navigatePages": 8,
"navigatepageNums": [
1
]
}
}
Name | Type | Description |
---|---|---|
code | String | 错误编码 |
message | String | 错误描述 |
Items | Object | 返回结果 |
id | Long | 唯一标识 |
name | String | 用户名称 |
address | String | 家庭住址 |
remark | String | 描述信息 |
来源:oschina
链接:https://my.oschina.net/zouxiangrd/blog/3217260