REST实践指南 葛亮@焦点科技 

大纲 一．REST简介 1. REST的益处 2. 浏览器支持问题 二．Restful URL最佳实践 1. 单数资源 2. 登录、退出 3. 嵌套资源 4. 改变资源状态 5. 同样资源，格式不同 6. 资源实体的其他信息 7. 搜索的URL 8. 同样资源，权限不同 9. 排序的URL 10. 最佳实践总结 

一．REST简介 1. REST的益处  将URL设计从混乱无序中解救出来  规范化URL的设计、命名 何谓混乱无序？ 如何解救？ 

1. REST的益处 • 以blog举例 – 设计blog的发表与查看URL – 加入评论功能 发表blog POST /blog.do?action=create 查看某篇blog GET /blog.do?action=show&id=1 查看所有blog GET /blog.do?action=list 发表评论 POST /blog.do?action=comment&blog_id=1 查看某个blog所有评论 GET /blog.do?action=show_comment&blog_id=1 有些坏味道了！ 是不是该有/comment.do？ 是不是该统一所有“动词”的名称？ 我们应该有规范！ 让REST来规范！ 

1. REST的益处 • REST方式的blog URL – 抽象出资源 – 资源对应唯一的URI – 用http method来表达语义 发表blog POST /blogs 获取某一篇blog GET /blogs/:id 修改某篇blog PUT /blogs/:id 删除某篇blog DELETE /blogs/:id method 语义 POST 表示创建 (CREATE) GET 表示读取、展示 (READ） PUT 表示更新、修改 (UPDATE) DELETE 表示删除 (DELETE) 获取所有blog GET /blogs 获取发表blog的页面 GET /blogs/new 获取修改blog的页面 GET /blogs/:id/edit 经典的 4种method 7种action 

一．REST简介 2. 浏览器支持问题 – 当前浏览器不支持PUT与DELETE – 替代方案 • POST代替 • 增加参数_method，值为PUT或DELETE 

二．Restful URL最佳实践 1. 单数资源 – 少一种action – 修改、删除不需要id 含义 http method URL 获取这个单数资源 GET /library 获取创建单数资源的页面 GET /library/new 获取修改单数资源的页面 GET /library/edit 删除这个单数资源 DELETE /library 创建这个单数资源 POST /library 修改这个单数资源 PUT /library 

二．Restful URL最佳实践 2. 登录与退出 – 登录 → 创建一种资源 – 退出 → 销毁一种资源 含义 http method URL 获取登录的页面 GET /session/new 登录 POST /session 退出 DELETE /session 

二．Restful URL最佳实践 3. 嵌套资源 – 依附于其他资源 – 例如：评论与blog 含义 method URL 查看某篇文章所有评论 GET /blogs/:blog_id/comments 查看某篇文章的某条评论 GET /blogs/:blog_id/comments/:id 获取为某篇文章添加评论的页面 GET /blogs/:blog_id/comments/new 获取修改某篇文章的某条评论的页面 GET /blogs/:blog_id/comments/:id/edit 为某篇文章添加评论 POST /blogs/:blog_id/comments 修改某篇文章的某条评论 PUT /blogs/:blog_id/comments/:id 删除某篇文章的某条评论 DELETE /blogs/:blog_id/comments/:id 嵌套不宜超过两层 

二．Restful URL最佳实践 4. 改变资源的状态 – 将blog置为可见或不可见 – 方案1：可见状态是一种资源 – 方案2：只是对资源的修改 – 方案3：对状态资源的修改 将blog置为可见 POST /blogs/:id/display 将blog置为不可见 DELETE /blogs/:id/display 将blog置为可见 PUT /blogs/:id display=1 将blog置为不可见 PUT /blogs/:id display=0 将blog置为可见 PUT /blogs/:id/status display=1 将blog置为不可见 PUT /blogs/:id/status display=0 

二．Restful URL最佳实践 5. 同样资源，格式不同 – 如何设计JSON内容的响应？ – 内容协商(Content Negotiation) – 使用http header中的Accept区分 – 替代方案：使用扩展名 含义 method URL Accept 获取一篇blog的HTML格式 GET /blogs/:id text/html 获取一篇blog的JSON格式 GET /blogs/:id application/json 含义 method URL 获取一篇blog的HTML格式 GET /blogs/:id.html 获取一篇blog的JSON格式 GET /blogs/:id.json 

二．Restful URL最佳实践 6. 资源实体的其他信息 – 添加 member action – 可以认为是一种嵌套资源 7. 搜索的URL – 添加 collection action – 依然可以认为是一种资源 含义 method URL 获取某篇blog的综合信息 GET /blogs/:id/info 含义 method URL 按关键词搜索blog GET /blogs/search?key=:keyword member action与collection action 并没有破坏REST规范性 

二．Restful URL最佳实践 8. 同样资源，权限不同 – blog的后台管理 – 添加命名空间 – 可以认为是两种资源 含义 method URL 游客获取所有blog GET /blogs 游客获取某一篇blog GET /blogs/:id 作者获取所有blog GET /admin/blogs 作者获取某一篇blog GET /admin/blogs/:id 

二．Restful URL最佳实践 9. 排序 – 添加参数 – 避免不必要的复杂性 含义 method URL 获取所有blog，按时间正序排列 GET /blogs?order=asc 

二．Restful URL最佳实践 10. 总结 • 抽象出资源很重要 • 资源与数据库的表并不一定一一对应 • 7种action不一定全部用到 • REST并不排斥在URL中加参数 • 理解不同，方案也会不同 • 有时候需要做一些妥协 

Thank You 2011-12-05