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).