RESTful最佳实践——四、定义

定义

幂等性

毫无疑问，这与听起来的正好相反，这些与某些功能紊乱的领域无关。来自维基百科：

在计算机科学中，术语幂等用于更全面地描述一个操作，一次或多次执行该操作产生的结果是一致的。根据应用的上下文，这可能有不同的含义。例如，在方法或者子例程调用具有副作用的情况下，意味着在第一调用之后被修改的状态也保持不变。

从REST服务端的角度来看，由于操作（或服务端调用）是幂等的，客户端可以用重复的调用而产生相同的结果–在编程语言中操作像是一个“setter”（设置）方法。换句话说，就是使用多个相同的请求与使用单个请求效果相同。注意，当幂等操作在服务器上产生相同的结果（副作用），响应本身可能是不同的（例如在多个请求之间，资源的状态可能会改变）。

PUT和DELETE方法被定义为是幂等的。然而如何查看http请求中delete警告信息，参照下文DELETE的部分。GET、HEAD、OPTIO和TRACE方法自从被定义为安全的方法后，也被定义为幂等的。参照下面关于安全的段落。

安全

来自维基百科：

一些方法（例如GET、HEAD、OPTIONS和TRACE）被定义为安全的方法，这意味着他们仅用于信息检索，不能更改服务器状态。换句话说，他们不会有副作用，除了相对来说无害的影响，例如日志、缓存。任意的GET请求，不考虑应用状态的上下文，被认为是安全的。

简而言之，安全意味着调用的方法不会引起副作用。因此，客户端可以反复的使用安全的请求，不用担心对服务端产生副作用。这意味着服务端须坚持GET、HEAD、OPTIONS和TRACE操作的安全定义。否则，除了是服务使用者混淆，它还会导致web端，搜索引擎和其他自动代理的缓存问题–将在服务器上发生意想不到的改变。

根据定义，安全操作是幂等的，因为他们在服务器上产生相同的结果。

安全的方法被实现为只读操作。然而，安全并不意味着服务器必须每次都返回相同的响应。

---

原文如下

Definitions

Idempotence

Contrary to how it sounds, make no mistake, this has no relation to certain areas of disfunction. From Wikipedia:

In computer science, the term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times. This may have a different meaning depending on the context in which it is applied. In the case of methods or subroutine calls with side effects, for instance, it means that the modified state remains the same after the first call.

From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can make that same call repeatedly while producing the same result—operating much like a “setter” method in a programming language. In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (side effects), the response itself may not be the same (e.g. a resource’s state may change between requests).

The PUT and DELETE methods are defined to be idempotent. However, read the caveat on DELETE in the HTTP Verbs, DELETE section below.

GET, HEAD, OPTIONS and TRACE methods are defined as idempotent also, since they are defined as safe. Read the section on safety below.

Safety

From Wikipedia:

Some methods (for example, HEAD, GET, OPTIONS and TRACE) are defined as safe, which means they are intended only for information retrieval and should not change the state of the server. In other words, they should not have side effects, beyond relatively harmless effects such as logging, caching, the serving of banner advertisements or incrementing a web counter. Making arbitrary GET requests without regard to the context of the application’s state should therefore be considered safe.

In short, safety means that calling the method does not cause side effects. Consequently, clients can make safe requests repeatedly without worry of side effects on the server. This means that services must adhere to the safety definitions of GET, HEAD, OPTIONS and TRACE operations. Otherwise, besides being confusing to service consumers, it can cause problems for Web caching, search engines and other automated agents—making unintended changes on the server.

By definition, safe operations are idempotent, since they produce the same result on the server.

Safe methods are implemented as read-only operations. However, safety does not mean that the server must return the same response every time.