RESTful Web Services 中文版 读书摘要 第五章

P109
统一接口意味着，在面向对象设计里被视为动词的事务，在面向资源的设计里必须被视为对象。在面向资源的架构里，一个读者不能“订阅”一个栏目，因为“订阅”不属于统一接口里的方法。必须通过另一个订阅对象来代表读者与栏目之间的关系。
如果要给我的资源增添新方法，就要为此定义一个新资源。
----------------------------
The uniform interface means that a resource-oriented design must treat as objects what an object-oriented design might consider verbs. In the ROA, a Reader can’t subscribe to a regularly appearing Column, because “subscribe to” is not part of the uniform interface. here must be a third object, Subscription, representing that relationship between a Reader nd a Column.
Whenever I’m tempted to add a new method to one of my resource “classes,” I’ll resolve the problem by defining a new kind of resource.

P109
设计资源的步骤：
（注：这里中英文没有一一对应）
1. 规划数据集
2. 把数据集划分为资源
对于其中每种资源：
3. 用 URI 为该资源命名
4. 设计发给客户端的表示
5. 用超链接和表单把该资源与已有资源联系起来
6. 考虑有哪些典型的事件经过
7. 考虑可能出现哪些错误情况
----------------------------
1. Figure out the data set
2. Split the data set into resources
For each kind of resource:
3. Name the resources with URIs
4. Expose a subset of the uniform interface
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia links and forms
8. Consider the typical course of events: what’s supposed to happen?
9. Consider error conditions: what might go wrong?

P112
一个资源就是任何值得作为超链接目标的事物
----------------------------
Remember that a resource is anything interesting enough to be the target of a hypertext link.

P113
服务暴露的资源可以分为三类：
为特别目的专门预定义的一次性资源
服务暴露的每一个对象所对应的资源
代表在数据集上执行算法的结果的资源
----------------------------
Web services commonly expose three kinds of resources:
Predefined one-off resources for especially important aspects of the application.
A resource for every object exposed through the service.
Resources representing the results of algorithms applied to the data set.

P117
要理解“把算法暴露为资源”这一方式，是需要一些时间的。你不要从动作（如“在地图上搜索地点”）方面来考虑，而要从该动作的结果方面来考虑（如“地图上符合搜索条件的地点”）。
----------------------------
It takes a while to get the hang of exposing an algorithm as a set of resources. Instead of thinking in terms of actions (“do a search for places on the map”), you need to think in terms of the results of that action (“the list of places on the map matching a search criteria”).

P117
根据集体经验，URI 设计有三条基本原则：
1. 用路径变量来表达层次结构： /parent/child
2. 在路径变量里加入标点符号，以消除误解： /parent/child1;child2
3. 用查询变量来表达算法的输入，例如： /search?q=jellyfish&start=20
----------------------------
There are three basic rules for URI design, born of collective experience:
1. Use path variables to encode hierarchy: /parent/child
2. Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2
3. Use query variables to imply inputs into an algorithm, for example: /search?q=jellyfish&start=20

P118
对于可按层次结构组织的作用域信息，采用路径变量是最好的方式。
----------------------------
Path variables are the best way to organize scoping information that can be arranged hierarchically.

P119
我建议：当作用域信息的次序有关紧要时，就用逗号，否则就用分号。
----------------------------
I recommend using commas when the order of the scoping information is important, and semicolons when the order doesn’t matter.

P129
表示传达资源状态，但它不必传达资源的全部状态，它只要传达部分状态就行了。
你可以通过跟随表示里的链接得到更多状态。
----------------------------
A representation conveys the state of its resource, but it doesn’t have to convey the entire state of the resource.
You can get as much of that state as you want by following its links to other resources.

P132
假如只能从本书得到一样东西，我希望那是你对“Web 服务就是为机器设计的网站”这一观念的理解（假若之前还没有的话）。
----------------------------
If you get only one thing out of this book, I hope it’s that this idea starts seeming natural to you (assuming it didn’t before).

P138
条件 HTTP GET 可以节省客户端和服务器的时间与带宽。它是通过两个响应报头（Last-Modified 和 ETag）和两个请求报头（IfModified-Since 和If-None-Match）实现的。
----------------------------
Conditional HTTP GET saves client and server time and bandwidth. It’s implemented with two response headers (Last-Modified and ETag), and two request headers (If- Modified-Since and If-None-Match).

P138
有些数据也许并不经常变化。
大部分时候，客户端对一个资源的第二次（及以后各次）HTTP 请求都是不必的。其实它们完全可以重用上一次请求时获得的表示。
----------------------------
This data is not constantly changing.
Most of the time, the client’s second and subsequent HTTP requests for a resource are wasted. They could have just reused the representation from their first request.

P138
每当服务器返回一个表示时，服务器应该为 Last-Modified 报头设置一个时间值，表示数据最后更新的时间。
客户端可以把这个最后更新时间保存下来，供以后使用。
当该客户端再次向同一个资源发送 GET 请求时，可以在 IfModified-Since 报头里提供那个最后更新时间。
假如资源的数据刚好在该客户端的两次请求之间发生了变化，服务器会返回响应代码 200（“OK”），并在实体主体里提供最新的表示——这就跟一次正常的 HTTP 请求一样。但是，假如数据没有变化，服务器将返回响应代码 304（“Not Modified”），并省去实体主体。这样，客户端就知道可以重用已缓存的表示了（因为数据没有改变）。
----------------------------
Whenever a server serves a representation, it should include a time value for the Last-Modified HTTP header. This is the last time the data underlying the representation was changed.
The client can store this value of Last-Modified and use it later.
The second time the client makes a GET request for that resource, it can provide that time in the If-Modified-Since header.
If the underlying data changed between the two requests, the server sends a response code of 200 (“OK”) and provides the new representation in the entity-body. That’s the same thing that happens during a normal HTTP request. But if the underlying data has not changed, the server sends a response code of 304 (“Not Modified”), and omits any entity-body. Then the client knows it’s okay to reuse its cached representation: the underlying data hasn’t changed since the first request.

P139
我还需要为不能处理的请求作考虑。假如遇到出错的情况，我会返回一个在 3xx、4xx、5xx 范围内的响应代码，并在 HTTP 报头里给出补充信息。假如响应包含实体主体，那肯定是一个描述错误状态的文档，而不是所请求资源的一个表示。
----------------------------
I also need to plan for requests I can’t fulfill. When I hit an error condition I’ll send a response code in the 3xx, 4xx, or 5xx range, and I may provide supplementary data in HTTP headers. If they provide an entity-body, it’ll be a document describing an error condition, not a representation of the requested resource (which, after all, couldn’t be served).

RESTful Web Services 中文版 读书摘要 第四章

P81
任何事物，只要具有被引用的必要，它就是一个资源。
----------------------------
A resource is anything that’s important enough to be referenced as a thing in itself.

P81
是什么令资源称得上是一个资源？它必须至少有一个 URI。URI 既是资源的名称，也是资源的地址。如果一则信息没有 URI ，它就不能算是一个资源，也不能算真正在 Web 上，而只能算作描述另一个资源的一些数据。
----------------------------
What makes a resource a resource? It has to have at least one URI. The URI is the name and address of a resource. If a piece of information doesn’t have a URI, it’s not a resource and it’s not really on the Web, except as a bit of data describing some other resource.

P86
在最终用户看来，Gmail 的 URI 始终是 https://mail.google.com/。无论作什么操作，无论从 Gmail 获取什么信息或向 Gmail 上传什么信息，你不会看到别的 URI。
Gmail有一个可寻址的版本，位于 URI https://mail.google.com/mail/?ui=html。
Gmail Web 服务是可寻址的，不过调用该服务的 Gmail Web 应用不是可寻址的。
----------------------------
From the end-user perspective, there is only one Gmail URI: https://mail.google.com/. Whatever you do, whatever pieces of information you retrieve from or upload to Gmail, you’ll never see a different URI.
Compare the Ajax interface against the more addressable version of Gmail you get by starting off at the URI https://mail.google.com/mail/?ui=html.
The Gmail web service is addressable, but the Gmail web application that uses it is not.

P90
无状态性意味着：有一种状态，是服务器不应该保存的。实际上，状态分为两种。从现在开始，我将区分应用状态与资源状态：前者应该保存在客户端，后者应该保存在服务端。
----------------------------
Statelessness implies there’s only one kind of state and that the server should go without it. Actually, there are two kinds of state. From this point on in the book I’m going to distinguish between application state, which ought to live on the client, and resource state, which ought to live on the server.

P90
每当客户端向服务器发请求时，请求里必须包含服务器处理该请求所需的所有应用状态。
各个客户端应当管理自己的应用状态。
----------------------------
This means that whenever a client makes a request, it must include all the application states the server will need to process it.
The client should be in charge of managing its own path through the application.

P95
将超媒体作为应用状态的引擎。
客户端应用状态在服务器提供的超媒体（即超文本表示里的链接和表单）的指引下发生变迁。
----------------------------
Hypermedia as the engine of application state.
The server guides the client’s path by serving “hypermedia”: links and forms inside hypertext representations.

P97
HTTP四种基本方法：
获取资源的一个表示：HTTP GET
创建一个新资源：向一个新 URI 发送 HTTP PUT，或者向一个已有 URI 发送 HTTP POST
修改已有资源：向已有 URI 发送 HTTP PUT
删除已有资源：HTTP DELETE
----------------------------
Retrieve a representation of a resource: HTTP GET
Create a new resource: HTTP PUT to a new URI, or HTTP POST to an existing URI
Modify an existing resource: HTTP PUT to an existing URI
Delete an existing resource: HTTP DELETE

P98
HEAD 请求就是比 GET 请求少返回实体主体而已。
----------------------------
HEAD gives you exactly what a GET request would give you, but without the entity-body.

P99
在一个 REST 式设计中，POST 通常被用于创建从属资源——即从属于“父”资源（另一个资源）而存在的资源。
----------------------------
In a RESTful design, POST is commonly used to create subordinate resources: resources that exist in relation to some other “parent” resource.

P99
PUT 与 POST 的区别就在于：假如是客户端负责决定新资源采用什么 URI，那就用 PUT；假如是服务器负责新资源采用什么 URI，那就用 POST。
----------------------------
The difference between PUT and POST is this: the client uses PUT when it’s in charge of deciding which URI the new resource should have. The client uses POST when the server is in charge of deciding which URI the new resource should have.

P100
给一个资源发 POST 请求，未必总是创建一个全新的从属资源。有时，当向一个资源 POST 数据时，它把你发来的信息附加到它自身的状态上，而不是用该信息新建一个资源。
----------------------------
The information conveyed in a POST to a resource doesn’t have to result in a whole new subordinate resource. Sometimes when you POST data to a resource, it appends the information you POSTed to its own state, instead of putting it in a new resource.

P102
假如对一个资源做某操作是幂等的，那么无论对该资源做多少次这种操作，结果总是一样的；对该资源的第二次及其后各次操作，不会令该资源的状态产生比第一次操作更多的影响。
----------------------------
an operation on a resource is idempotent if making one request is the same as making a series of identical requests. The second and subsequent requests leave the resource state in exactly the same state as the first request did.

P103
幂等性对实践提出的要求是：不要允许客户端对资源状态做相对的改动。比如一个资源把某个数值作为其部分资源状态来保存，客户端可以通过 PUT 操作把该数值设为 4、0 或 -50，但是它不应通过 PUT 操作对该值作“加一”操作。
----------------------------
The practical upshot of this is that you shouldn’t allow your clients to PUT representations that change a resource’s state in relative terms. If a resource keeps a numeric value as part of its resource state, a client might use PUT to set that value to 4, or 0, or -50, but not to increment that value by 1.

P103
POST 既不是安全的，也不是幂等的。
----------------------------
POST is neither safe nor idempotent.

RESTful Web Services 中文版 读书摘要 第二章

P28
服务器应该是理想主义的；客户端必须是实用主义的——这是 Postel 法则“严以律己，宽以待人”的一个变形。
----------------------------
Servers should be idealistic; clients must be pragmatic. This is a variant of Postel’s Law: “Be conservative in what you do; be liberal in which you accept from others.”

P47
JSON 适用于表达数据结构；而 Web 提供的主要是文档——一种不规则的、自描述的、相互链接的数据结构。XML 和 HTML 专门用于表达文档。
----------------------------
JSON is good for representing data structures in general, and the Web mainly serves documents: irregular, self-describing data structures that link to each other. XML and HTML are specialized for representing documents.

RESTful Web Services 中文版 读书摘要 第一章

P13
REST式架构意味着，方法信息都在HTTP方法里；面向资源的架构意味着，作用域信息都在URI里。
----------------------------
In RESTful architectures, the method information goes into the HTTP method. In Resource-Oriented Architectures, the scoping information goes into the URI.

P17
Flickr web API 是一种 REST-RPC 混合架构：当客户端通过GET方法获取数据时，它是REST式的；当客户端通过GET方法修改数据时，它是RPC式的。
----------------------------
The Flickr web API is a REST-RPC hybrid: RESTful when the client is retrieving data through GET, RPC-style when the client is modifying the data set.

P18
一个 REST 式面向资源的服务为客户端可能操作的每一则数据暴露一个 URI；一个 REST-RPC 混合服务，为客户端可能进行的每一个操作暴露一个 URI（比如获取数据用一个 URI，删除数据用另一个 URI）；一个 RPC 式服务，为每个处理远程调用的进程暴露一个URI，一般来说这样的URI只有一个，即服务的“端点”。
----------------------------
A RESTful, resource-oriented service exposes a URI for every piece of data the client might want to operate on. A REST-RPC hybrid exposes a URI for every operation the client might perform: one URI to fetch a piece of data, a different URI to delete that same data. An RPC-style service exposes one URI for every processes capable of handling Remote Procedure Calls (RPC). There’s usually only one such URI: the service “endpoint.”

P20
REST 式架构的主要竞争对手是 RPC 式架构，而不是 SOAP 这样特定的技术。没错，几乎所有现有的基于 SOAP 的服务都属于 RPC 式架构，但 SOAP 跟 HTTP 一样，只是一种把文档放在信封里的方式。
----------------------------
The primary competitors to RESTful architectures are RPC architectures, not specific technologies like SOAP. It is true that basically every SOAP service that now exists has an RPC architecture, but SOAP is just a way of putting a document in an envelope with stickers on it, like HTTP.

RESTful Web Services 中文版 - Preface

读完了样章的前言，发现了这样一段有趣的文字：

除非为了示范特定的框架或语言，否则我们将采用Ruby(http://www.ruby-lang.org)语言来描述。
我们选用Ruby是因为：即使对于不懂Ruby的程序员来说，它也是简洁易读的。（因为这是一门很好的语言，而且它的名字跟Sam的姓有着令人困惑的联系。）Ruby的标准Web框架——Ruby on Rails——也是最主要的一种REST式Web服务实现平台之一。如果你不懂Ruby也没关系，我们在代码中嵌入了许多有助于理解Ruby语法的注释。
----------------------------
But whenever we’re not demonstrating a specific framework or language, we use Ruby (http://www.ruby-lang.org/) as our implementation language.
We chose Ruby because it’s concise and easy to read, even for programmers who don’t know the language. (And because it’s nice and confusing in conjunction with Sam’s last name.) Ruby’s standard web framework, Ruby on Rails, is also one of the leading implementation platforms for RESTful web services. If you don’t know Ruby, don’t worry: we include lots of comments explaining Ruby-specific idioms.

这个Sam应该就是Agile Web Development with Rails, Third Edition新加入的作者，当时我就在想怎么会有这么巧的事呢，呵呵。

RESTful Web Services中文版

最先是从InfoQ中文站(here)上看到的介绍。
这是中文版的官网：http://www.restfulwebservices.cn/
去china-pub(here)上看了下，标的是5月出版，貌似刚刚上架。
样章读了一点，翻译得还不错。去淘宝订了一本，居然50都不到（原价70），真便宜啊，都不知道他从什么渠道进的货（盗版无论如何是出不了这么快的），能赚多少钱。
订完后又去官网上看了看，结果发现官网上订是免运费的，算下来和在淘宝上订花的钱是一样多。
本来还想订一本Everyday Scripting with Ruby 中文版（也是最近新出的，以前看过一点英文版的），终于还是忍住了，拒绝当收藏狂。
从china-pub和w3china.org下的样章，打开后顶上赫然挺立着“Microsoft Word - xx.doc”的字样，而从InfoQ中文站下的样章就没有，我想这就是InfoQ更细心一点点，更专业一点点的体现吧。
---------------------------------
找了个英文版的下载。
来源：http://www.matrix.org.cn/thread.shtml?topicId=a5f22fb0-61a6-11dc-acc8-0fa2717adfd4&forumId=29&fid=29