RESTful | zKing的学习乐园

摘要

REST即表述性状态传递（英文：Representational State Transfer，简称REST）
表述性状态转移是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful

# 基本架构的四个方法

GET - 用于获取数据。
PUT - 用于更新或添加数据。
DELETE - 用于删除数据。
POST - 用于添加数据。

# 开发 RESTful 风格的 API

# 关于对 URL 的处理

在实际工程中，一个Web应用既有REST，还有MVC，可能还需要集成其他第三方系统。如何组织URL？

一个简单的方法是通过固定的前缀区分。例如，/static/开头的 URL 是静态资源文件，类似的，/api/开头的 URL 就是 REST API，其他 URL 是普通的 MVC 请求。

实践上常见的设计:

在 URI 里边带上版本号

如github开放平台的API：http://developer.github.com/v3/ 可以发现，一般的项目加版本v1，v2，v3版本号，为的是兼容一些老版本的接口，这个加版本估计只有大公司大项目才会去使用。

URL 命名规范

每个 URL 代表一种资源，所以 URL 中不能有动词，只能有名词，并且名词中也应该使用复数。实现者应使用相应的 Http 动词 GET、POST、PUT、PATCH、DELETE、HEAD 来操作这些资源即可。另外可以使用 query parameter 加以辅助，可以采用驼峰命名法，也可以采用下划线命名的方式来进行命名。

http://example.com/api/users               //GET 获取所有用户信息
http://example.com/api/users/1           //GET 获取标识为1用户信息
http://example.com/api/users/1          //DELETE 删除标识为1用户信息
http://example.com/api/users/1         //Patch 更新标识为1用户部分信息,包含在div中
http://example.com/api/users           //POST 添加新的用户
http://example.com/api/users/today_login 获取今天登陆的用户
http://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列

# 统一输出 REST

RESTful 架构的核心规范与约束：统一接口和一致的数据格式

REST 请求和普通的 HTTP 请求有几个特殊的地方：

REST 请求仍然是标准的 HTTP 请求，但是，除了GET请求外，POST、PUT等请求的body是JSON数据格式，请求的HTTP头中，Content-Type:application/json
REST 响应返回的结果是 JSON 数据格式，因此，响应 HTTP 头的也是Content-Type:application/json。

REST规范定义了资源的通用访问格式为 JSON，虽然它不是一个强制要求，但遵守该规范可以让人易于理解。

# 处理错误

问题

当 REST API 请求出错时，如何返回错误信息？
当客户端收到 REST 响应后，如何判断是成功还是错误？

在涉及到 REST API 的错误时，我们必须先意识到，客户端会遇到两种类型的 REST API 错误。

类似403，404，500等错误，这些错误实际上是HTTP请求可能发生的错误。
业务逻辑的错误，例如，输入了不合法的Email地址，试图删除一个不存在的Product，等等。这种类型的错误信息是一个 JSON 字符串

关于第二种类型的 REST API 错误，可以使用以下的 JSON 示例作为错误码的规范

{
    "code": "错误代码",
    "message": "错误描述信息"
}

强烈建议使用字符串作为错误码，原因在于，使用数字作为错误码时，API提供者需要维护一份错误码代码说明表，并且，该文档必须时刻与API发布同步，否则，客户端开发者遇到一个文档上没有写明的错误码，就完全不知道发生了什么错误。
错误代码命名规范为大类:子类，例如，口令不匹配的登录错误代码为auth:bad_password，用户名不存在的登录错误代码为auth:user_not_found。这样，客户端既可以简单匹配某个类别的错误，也可以精确匹配某个特定的错误。

示例

{
    "code": "auth:user_not_found",
    "message": "user_not_found"
}

当 REST API 请求出错时，如果是 http 请求的错误，应该返回正确的状态码。如果是业务逻辑错误，应该返回可读的错误码
客户端收到 REST 响应后，如果是 http 请求错误是可以直接显示的。如果是逻辑错误，则可以通过判断 res.code 是否存在来进行响应

# 总结

RESTful 实质上是由于前后端分离的技术盛行，然后为了解决如何设计出一个便于理解，容易使用的api这个问题而产生的 API 规范/风格。

每一个 URI 代表一种资源
客户端（Client）请求是无状态的，只能通过四个 HTTP动词 GET，POST，PUT，DELETE，对服务器端资源进行操作，用 query parameter 加以辅助，实现”表现层状态转化”。
对于客户端的请求，服务端（Server）应该返回统一的数据格式，并合理处理错误信息进行返回