协议：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次，对资源状态改变的效果是等价的。

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 起始记录）

例：

获取前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"

　　　　　　　　]

        }

  }  

}

restful 风格 web api规范