RESTful API 设计最佳实践（4）

RESTful API 设计最佳实践（4）

目前，对于RESTful API设计并没有非常严格的标准，虽然设计的API可能（keding）达不到原作者Roy Thomas Fielding的要求，但一定要尽量满足以下需求：

（1）使用WEB标准，如满足HTTP协议规范。
（2）对开发者友好，并且可以通过浏览器、curl等简单工具进行调用。
（3）简单、易用、一致。
（4）高效。

这一章节，我想先介绍一下REST中统一接口的相关理论。

一、统一接口

在Roy Fielding的论文中，对REST的统一接口提出了四个约束：

1. 基于资源

REST的数据元素可以总结如下表：



关于REST中的资源，需要再强调一下：

rest对于资源的定义基于一个简单的前提：标识符的改变应该尽可能少的发生，将一个资源定义为创作者想要标识的语义，而不是对应于创建这些引用时的那些语义的值。因此，资源定义为一个URI标识了的概念，而不是一个标识了的文档。这是我们在定义资源时的依据，也决定我们定义的接口是否是足够通用和统一接口。REST中的资源所指的不是数据，而是数据和表现形式的组合，比如“我的粉丝”和“我关注的人”在数据上可能有重叠或者完全相同，而由于他们的表现形式不同，所以被归为不同的资源。

在对资源进行定义时，一定要使用名称定义资源或资源集合：** 在设计REST服务或RESTful API时，必须使用名次来表达，不能使用动词，这是防止掉入RPC陷阱的最基本一环。

另外，对于选择用名词单数形式还是复数形式来定义资源也是需要仔细考虑的，通常建议是用复数来表示，那样会给服务带来更大的灵活性和可扩展性（当然，如果确定有些资源是绝对只有一个的，那可以用单数形式精确表述）。

2. 通过资源的表述来操作资源

从上面表格可以看出，REST中的数据应该是包含了资源相关的描述信息，包括操作信息（如cache-control等），根据这些表示信息，就可以对相应的资源进行操作

3. 自描述的消息

每条消息都应该包含足够的信息，以提供客户端处理所需的描述。比如消息的编码格式是utf-8的，是html文本的还是json格式的等。

4. 以超媒体作为应用状态的驱动

在客户端与服务器的交互过程中，客户端可以将状态放在body中，URL的查询变量中，消息头Header中，以及URI指向资源的路径中传递给服务器端。而服务器端则可以将资源的状态放在报文body中，回应状态码中以及消息头Header中传递给客户端。另外，如果需要的话，可以在返回的消息中，加入超链接（比如新增一个资源后，在Header中返回指向该资源的超链接，或者返回指向相关联资源的超链接）。

二、后续

上面主要介绍了在REST服务中，统一接口所要遵循的约束，以及设计原则。但更多是的一种宽泛的理论介绍，在下一章中，将着重介绍REST统一接口的实践者——HTTP规范。