协议：http/https
域名 ： http://api.example.com/xxx/xxx
api: 标明api接口服务
xxx: 服务
xxx: 资源
版本控制：
一、使用MediaType，即在请求头header中做版本控制，数据格式等控制
想要获取的资源格式
GET /user/123456 HTTP/1.1
Accept: application/vnd.123456.user-v3+json
获取v3版userid为123456 的用户信息,返回资源格式为json
响应的文本格式
HTTP/1.1 200 OK
Content-Type: application/vnd.123456.user-v3+json
{"user": {userId":"123456","name":"张三"} }
服务端响应v3版userId为123456 的用户信息,返回资源格式为json
严格遵守restful风格,可读性差
二、URI中添加版本信息
http://api.example.com/v1/xxx/xxx
缺点：版本的不同会导致同一个资源对应多个uri,后期维护非常麻烦（亲身经历，令人头疼）
三、通过传输固定参数字段 version,比较折中的方法，维护也比较方便
动词（动作）：
GET 获取资源
POST 创建资源
PUT 更新资源（客户端提供改变后的完整资源）
PATCH 更新资源（客户端提供改变的属性）
DELETE 删除资源
HEAD 获取资源元数据
OPRATIONS 获取资源属性，哪些是可修改的，属性描述等等
例：GET /user/{userId} 获取用户信息
POST /user 创建用户
PUT /user/{userId} 更新项目信息
DELETE /user/{userId} 删除项目信息
安全和幂等
安全性：不会改变资源状态，可以理解为只读的；
幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。
|
|
安全性 |
幂等性 |
|
GET |
√ |
√ |
|
POST |
× |
× |
|
PUT |
× |
√ |
|
PATCH |
× |
√ |
|
DELETE |
× |
√ |
|
HEAD |
√ |
√ |
|
OPRATIONS |
√ |
√ |
URI规则：
1、uri 标志唯一资源，语义明确
例：用户服务
/user/users/{userId}
GET /user/users/{userId} 表示查询
PUT /user/users/{userId} 表示更新
单个项目是网络上的资源，一个uri唯一标识，不应该根据操作的不同，版本的不同而改变
2、单/复数查询
复数以对应单数名词的复数形式表示
例：
获取用户信息
GET /user/users/{userId}
获取所有用户
GET /user/users
获取某个用户的所有订单信息
GET /user/users/{userId}/orders
获取某个用户的所有某个订单信息
GET /user/users/{userId}/orders/{orderId}
2、复杂查询
restful 允许url 冗余，允许以 ？name=value的形式过滤资源信息（根据业务的具体情况需要定义一些约定参数，例order排序方式，limit 每页记录 offset 起始记录）
|
|
表示 |
备注 |
|
过滤条件 |
?status=1&type=2 |
资源也可以表示为 /user/users?userId=123456 /user/users/123456 |
|
排序 |
?sort=time,desc |
|
|
投影 |
?selectlist=userId,name,status |
|
|
分页 |
?limit=10&offset=1 |
|
例：
获取前10条用户数据
GET /user/users?limit=10
获取第一页用户数据，每页显示10条
GET /user/users?offset=1&limit=10
按时间倒排序获取第一页项目数据，每页显示10条
GET /user/users/?offset=1&limit=10&sort=time,desc
响应数据
响应数据尽可能包含全面信息
{
//response 状态信息
"statusCode": 404,
"statusLine": HTTP/1.1 200 OK,
"requestData":{"limit":10,"offset":1},
"responseData":{
//业务状态
errorCode:20001
errorMessage:"签名无效"
data{
"paging":{"limit":10,"offset":1,"total":100},
"users":[{},{},{}]
}
}
}
响应数据可以包含另一个资源的请求信息信息
{
//response 状态信息
"statusCode": 200,
"statusLine": HTTP/1.1 200 OK
"requestData":{"userId":"123456"},
"responseData":{
//业务状态
errorCode:1
errorMessage:"成功"
data{
"user":["userId":"123456",
"blod":"http://blod.exmple.com/userId=123456"
]
}
}
}