RESTful介绍及示例

RESTful的中文含义是“ 表现层状态传递”，完整表述是：Resource Representational State Transfer，简写成REST，其中Resource被省略了。

RESTful介绍

---

RESTful资源-Resource

RESTful中的Resource是网络中的资源，如“文本”、“图片”。
资源我们用URI来表示，重点用于表示资源的位置。

RESTful表现层-Representational

RESTful表现层是针对Resource，一个Resource可以用多种表示形式，如：文本的表现形式可以是：txt，html，xml等，图片的表现形式可以是：png，jpg 等。

表现层我们用http协议中的content-type和accept来表示，重点用于表示表现形式
Accept:application/json http://localhost:8080/book/123 表示请求json格式的book
Accept:application/xml http://localhost:8080/book/123 表示请求xml格式的book

RESTful状态转化-State Transfer

RESTful状态转化又是针对表现层的，分别用http的GET、POST、PUT、DELETE方法

• GET - 获取资源
  GET具有幂等性(每次HTTP请求相同的参数，相同的URL，产生的结果是相同的）

• POST - 创建资源
  创建资源，如果资源已存在，返回http状态码201(Created)，由于多次请求，每个创建资源的uri都不相同，因些不具有幂等性

• PUT - 创建或更新资源
  如果资源不存在则创建资源，如果资源已存在则更新资源，多次请求，资源的uri都是相同，具有幂等性

• DELETE - 删除资源
  具有幂等性

RESTful的URI设计示例

---

RESTful 的核心思想也是通过这些动词 + 名词完成对资源的操作与访问。

• 动词：常用4个(GET，POST，PUT，DELETE，GET/PUT/DELETE 是幂等的)
• 名词：就是表示一个资源或者服务，如 /user，/teacher
• 动词+名词组合：

  资源	POST	GET	PUT	DELETE
  /user	创建用户	查询所有用户	批量更新用户	删除所有用户
  /user/001	不被允许(405)	查询001这个用户	更新001这个用户	删除001这个用户

URL 层级

单一资源的URL按上的规则就可以很好定义，但资源的相互关联与嵌套很常见，查找id是12的用户的所有帖子：

GET  /posts?userId=12

版本

通过 URL 加版本的方式可以更好的发现资源，如：

POST /v2/users
GET /V1/users/12

过滤/分页/排序

过滤

GET /users/12/posts?state=published，/users/12/posts?published=true

分页

GET /users?pageNo=1&pageSize=20

排序

GET /users?sort=score_desc

资源命名约定和URI格式

• 使用正斜杠（/）表示层次关系，如：

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

• 不要在URI中使用尾部正斜杠，如

 http://api.example.com/device-management/managed-devices/

• 使用连字符（ - ）来提高URI的可读性

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location（推荐）
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation 

• 不要使用下划线（）
  可以使用下划线代替连字符作为分隔符 - 下划线（）字符可能会在某些浏览器或屏幕中被部分遮挡或完全隐藏。为避免这种混淆，请使用连字符（ - ）而不是下划线（_）

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location （推荐）
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location

• 在URI中使用小写字母
  方便时，URI路径中应始终首选小写字母。

参考：http://restful.p2hp.com