REST實戰(中文版超媒體和系統架構)
Bear在這裡買的
amazon的參考
-----------------------------------------------------------
作者：(美)韋伯//帕拉斯泰迪斯//魯濱遜|譯者:李錕//俞黎敏//馬鈞//崔毅
出版社：東南大學
ISBN：9787564129651
出版日期：2011/09/01
頁數：388
人民幣：RMB 78 元
-----------------------------------------------------------
Bear: 這本書很棒，但一定要同時對照書上的圖及範例才會看的懂。
P.62(原文P.56)
參考原文圖
Figure 4-1. Possible states for an order
Figure 4-2. CRUD ordering service high-level architecture
P.62(原文P.56)
對於訂單的每一種操作都可以映射到某個HTTP動詞。例如，我們用POST創建新訂單，用GET獲取訂單詳情，用PUT更新訂單，用DELETE刪除訂單。
(Bear: 這裡的POST及PUT用法和書後面建議的用法不同，可對照P.113(原文P.112)的圖及P.114的說明)
Each operation on an order can be mapped onto one of the HTTP verbs. For example, we use POST for creating a new order, GET for retrieving its details, PUT for updating it, and DELETE for, well, deleting it. When mixed with appropriate status codes and some commonsense patterns, HTTP can provide a good platform for CRUD domains, resulting in really simple architectures, as shown in Figure 4-2.
P.63(原文P.57)
參考原文圖
Table 4-1. The ordering service contract overview
P.73(原文P.68)
For the uninitiated, HTTP can be a strange protocol, not least because it offers two
ways of transmitting information from client to server with the POST and PUT verbs. In
their landmark book, Richardson and Ruby established a convention for determining
when to use PUT and when to use POST to resolve the ambiguity:
Use POST to create a resource identified by a service-generated URI.
Use POST to append a resource to a collection identified by a service-generated URI.
Use PUT to create or overwrite a resource identified by a URI computed by the client.
P.74(原文P.69)
In Figure 4-6, consumers know the URI of the order they want to update from the
Location header received in the response to an earlier POST (create) request. Using that
URI, a consumer can PUT an updated order representation to the ordering service. In
accordance with the HTTP specification, a successful PUT request won’t create a new
resource or produce a new URI. Instead, the state of the identified resource will be
updated to reflect the data in the request representation.
P.75(原文P.70)
PUT expects the entire resource representation to be supplied to the server, rather
than just changes to the resource state. Another relatively unknown HTTP verb,
PATCH, has been suggested for use in situations—typically involving large resource
representations—where only changes are provided. We’ll use PUT for now, but we’ll
also cover the use of PATCH in the next chapter.
P.76(原文P.71~72)
In keeping with the HTTP specification, the response body includes enough information
for the client to understand and potentially fix the problem, if at all possible. To
that end, Example 4-16 shows that the ordering service returns a representation of the
current state of the order resource from the service. In the payload, we can see that
the
be altered. To make progress, the consumer will have to interpret the status code and
payload to determine what might have gone wrong.
As with errors when processing POST and GET, a 500 response code is equally straightforward
when using PUT—simply wait and retry. Since PUT is idempotent—because
service-side state is replaced wholesale by consumer-side state—the consumer can safely
repeat the operation as many times as necessary. However, PUT can only be safely used
for absolute updates; it cannot be used for relative updates such as “add an extra shot
to the cappuccino in order 1234.” That would violate its semantics.
PUT is one of the HTTP verbs that has idempotent semantics (along with GET and
DELETE in this chapter). The ordering service must therefore guarantee that PUTting
the same order many times has the same side effects as PUTting it exactly once.
This greatly simplifies dealing with intermittent problems and crash recovery by
allowing the operation to be repeated in the event of failure.
P.80(原文P.76)
Some services may elect to return the final state of the deleted resource on the
HTTP response. In those cases, 204 isn’t appropriate, and a 200 OK response along
with Content-Type and Content-Length headers and a resource representation in
the body is used.
P.82(原文P.78)
We saw in Chapter 3 that GET is special since it has the properties of being both safe
and idempotent. PUT and DELETE are both idempotent, but neither is safe, while POST is
neither safe nor idempotent. Only GET returns the same result with repeated invocations
and has no side effects for which the consumer is responsible.
P.113(原文P.112)
參考原文圖
Figure 5-4. Possible HTTP requests for the Restbucks ordering service
P.114~115(原文P.114)
Resources Updates: PUT Versus POST
In Chapter 4, our CRUD service used PUT to update the state of a resource, whereas in
our hypermedia service, we’re using POST—a verb we’d normally associate with resource
creation.
We’ve made this change because of the strict semantics of PUT. With PUT, the state encapsulated
by the incoming representation will, if legal, wholly replace the state of the resource
hosted by the service. This obliges a client to PUT all the resource state, including any links,
as part of the representation it sends. But since, in this example, clients have no business
sending links to a service, we can’t expect them to use PUT.
At the time of this writing, a new verb called PATCH has become an Internet RFC under
the auspices of the IET F.* Unlike PUT, PATCH is neither safe nor idempotent, but it can be
used to send patch documents (diffs) over the wire for partial resource modification. Using
PATCH, a consumer could legally transmit the business information portion of the order
to the Restbucks service, which would then apply the information to an existing order
resource and update links as necessary.
PATCH has only recently become an Internet standard (as RFC5789) and is not yet widely
supported. Until that situation changes, we will continue to send partial updates to the
service using POST.
P.119(原文P.119)
Example 5-9 contains two elements that allow us to infer the state of the distributed
application. The
confirmation that the order has been paid for. This sense of application state is reinforced
at the protocol level by the presence of a single element, which directs the
consumer toward the order resource and the end of the business process. And because
the payment link is now absent, the consumer has no way of activating that part of the
protocol.
P.125(原文P.125)
We recommend that proprietary link relation values take the form of fully qualified
URIs, which, if dereferenced, return a human-readable description of the
link semantic. That way, processors that report the presence of an unknown link
relation value can include the link relation description in any log output, thereby
documenting the evolution of the application. elements and rel attributes
thus provide a high degree of discoverability.
P.146(原文P.149)
It could be argued that PaymentExpected should be the initial state and that the PUT request would
create the payment resource. However, the semantics of the initial state in the DSL are such
that we expect an HTTP request to be sent to the URI template without the {id} part. Since the
payment resource was already created through code, rather than due to a request initiated by a
consumer, we need to instruct the hypermedia framework to perform this automatic transition
without expecting an initial request.
