Restful Web服务如何设计

Rest基于Roy Thomas Fielding博士论文

中文翻译

原版论文

从下面几个方面来设计一个好的restful web服务

• 识别资源
• 选择合适的资源粒度
• 设计 URI
• 选择合适的 HTTP ⽅法和返回码
• 设计资源的表述

1.识别资源

• 找到领域名词 :
         能⽤ CRUD 操作的名词. 比如用户,账户
• 将资源组织为集合（即集合资源）
         将资源组合到一起,比如用户集合
• 将资源合并为复合资源
          将用户和账户组合
• 计算或处理函数
  使用资源计算处理逻辑

2.选择合适的资源粒度

服务端的⻆度

• ⽹络效率  
• 表述的多少: 一次请求中表达更多的事情

• 客户端的易⽤程度: 怎么整合资源给客户端

客户端的⻆度

    • 可缓存性:当前数据是否课缓存

    • 修改频率:当前数据修改频率是否高

    • 可变性:数据是否可以修改

3.设计 URI

构建URI的一些规则

• 使⽤域及⼦域对资源进⾏合理的分组或划分
• 在 URI 的路径部分使⽤斜杠分隔符 ( / ) 来表示资源之间的层次关系
• 在 URI 的路径部分使⽤逗号 ( , ) 和分号 ( ; ) 来表示⾮层次元素
• 使⽤连字符 ( - ) 和下划线 ( _ ) 来改善⻓路径中名称的可读性
• 在 URI 的查询部分使⽤“与”符号 ( & ) 来分隔参数
• 在 URI 中避免出现⽂件扩展名 ( 例如 .php，.aspx 和 .jsp )

4.选择合适的 HTTP ⽅法和返回码

URI	Http Method	description
/user/	GET	获取全部用户信息
/user/	POST	添加新的用户信息
/user/{id}	GET	获取特定用户信息
/user/{id}	DELETE	删除特定用户信息
/user/{id}	PUT	修改特定用户信息

5.设计资源的表述

每个接口返回不同的表述类型,常用的表述类型有:

JSON,XML,HTML,ProtoBuf.