RESTful 规范

1. 基本概念

    REST全称是Representational State Transfer，中文意思是表征性状态转移。指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。如果后台开发遵守了REST风格便可称为RESTful。

REST本身并没有创造新的技术，是一种软件架构风格，以更好地使用现有Web标准中的一些准则和约束。结构清晰、符合标准、易于理解、扩展方便。

    RESTful架构是对MVC架构改进后所形成的一种架构，通过使用事先定义好的接口与不同的服务联系起来。在RESTful架构中，浏览器使用POST，DELETE，PUT和GET四种请求方式分别对指定的URL资源进行增删改查操作。因此，RESTful是通过URI实现对资源的管理及访问，具有扩展性强、结构清晰的特点。

RESTful架构的特点：

• 每一个URI代表一种资源；
• 客户端使用GET（查询）、POST（增加）、PUT（更新）、DELETE（删除）四个表示操作方式的动词对服务端资源进行操作；
• 通过操作资源的表现形式来操作资源；

2. 规范要求

2.1 URI不能包含动词，只能有名词

名词往往与数据库的表名对应。比如：

GET /products ：将返回所有产品清单
POST /products ：将产品新建到集合
GET /products/4 ：将获取产品 4
PUT /products/4 ：将更新产品 4

下面写法是错误的写法，比如：/posts/show/1。这里的show是动词，这里就设计错了。正确写法为/posts/1，然后用GET方法表示show。

2.2 版本号

应该将API的版本号放入URL。
比如：

1.0： http://www.example.com/app/1.0/foo
1.1： http://www.example.com/app/1.1/foo
2.0： http://www.example.com/app/2.0/foo

另一种做法就是将版本号放置在HTTP请求头部的Accept或者Content-Type字段中进行区分，比如：

1.0: vnd.example-com.foo json; version=1.0
1.1: vnd.example-com.foo json; version=1.1
2.0: vnd.example-com.foo json; version=2.0

也可以使用时间戳来替代，比如：

June 2008: http://www.example.com/app/2008/06/foo
October 2009: http://www.example.com/app/2009/10/foo
February 2010: http://www.example.com/app/2010/02/foo

2.3 返回数据格式

返回资源默认为JSON，当然也可以是XML格式的文件，所以需要指定：

XML: http://www.example.com/app/1.0/foo?format=xml
JSON: http://www.example.com/app/1.0/foo?format=json

应该尽量使用JSON，避免使用XML。

2.4 状态码必须精确

客户端每一次请求，服务端都必须给出回应，回应包括HTTP状态码和数据两部分。

3. 前后差别对别

在Restful API接口规范一文中提到，使用前和使用后的案例：

非REST设计：

http://localhost:8080/admin/getUser （查询用户）
http://localhost:8080/admin/addUser （新增用户）
http://localhost:8080/admin/updateUser （更新用户）
http://localhost:8080/admin/deleteUser （删除用户）

不同的URL（主要为使用动词）进行不同的操作。

REST架构：

GET http://localhost:8080/admin/user （查询用户）
POST http://localhost:8080/admin/user （新增用户）
PUT http://localhost:8080/admin/user （更新用户）
DELETE http://localhost:8080/admin/user （删除用户）

URL只指定资源，以HTTP方法动词进行不同的操作。

给人的感觉更加清爽。以后开发需要注意，慢慢向RESTful 规范靠拢。

Thanks

• Restful API接口规范
• RESTful 架构详解
• RESTful百度百科
• 理解RESTful架构
• Versioning REST Services

这篇好文章是转载于：学新通技术网