Professional Documents
Culture Documents
Một trong những ý tưởng hữu ích nhất của Semantic Web là một tài nguyên có thể được phân loại theo một
hoặc nhiều loại tài nguyên (còn được gọi là các loại ngữ nghĩa trừu tượng hoặc chỉ các loại ngữ nghĩa).
Đây không giống như các kiểu dữ liệu trong ngôn ngữ lập trình. Chúng là sự phân loại, giống như thể
Thuộc tính loại của RDF gán một loại cho tài nguyên. Giống như mọi thứ khác trong RDF, các loại tài
nguyên được xác định bằng URI. Đây là mô tả về tài nguyên (http://example.com/ ~omjennyg) được phân
Turtle định nghĩa a là lối tắt cho thuộc tính loại của RDF nên bạn không cần phải mang theo
Từ vựng RDF vào từng tài liệu của Turtle chỉ để nói về các loại tài nguyên:
Đôi khi, khái niệm “loại tài nguyên” thoát ra khỏi thế giới Web ngữ nghĩa và đi vào thế giới API web
rộng lớn hơn. Trong định dạng XLink (Chương 10), một liên kết có thể có thuộc tính vai trò cung cấp
<a xlink:href="http://example.com/~omjennyg"
xlink:arcrole="http://alps.io/iana/relations#author"
xlink:role="http://schema.org/Person">
Trong Định dạng liên kết CoRE mà tôi sẽ đề cập trong chương tiếp theo, thuộc tính rt của liên kết
truyền tải loại tài nguyên ở đầu bên kia (“rt” là viết tắt của “loại tài nguyên”):
<http://example.com/~omjennyg>;rel="author";rt="http://schema.org/Person"
Mối quan hệ liên kết và loại tài nguyên là hai thứ khác nhau. Loại tài nguyên (http:// lược đồ.org/
Person) là một tuyên bố về tài nguyên ở đầu bên kia của liên kết. Mối quan hệ liên kết (tác giả hoặc
http://alps.io/iana/relations#author) là một tuyên bố về chính liên kết—về mối quan hệ giữa hai tài
nguyên.
Nói về các mối quan hệ liên kết, có một mối quan hệ liên kết đã đăng ký IANA được gọi là loại cho phép
một đại diện đưa ra các xác nhận về loại tài nguyên của chính nó:
HTTP/1.1 200 OK
Loại nội dung: text/plain
Liên kết: <http://schema.org/birthDate>;rel="type"
25-08-1987
Các thuộc tính vai trò và rt rất hữu ích. Chúng cho phép khách hàng nhìn về phía trước để xem loại tài
nguyên nào ở đầu bên kia của liên kết. Nếu khách hàng thích những gì họ nhìn thấy, họ có thể tiếp tục
và theo liên kết.
Nhưng làm thế nào khách hàng có thể biết liệu họ có thích những gì họ nhìn thấy hay không? Khái
niệm “loại tài nguyên” xuất phát từ RDF và trong RDF, http://schema.org/Person, không phải là
một URL. Đó là một URI, một mã định danh vô nghĩa. Máy khách không được mời thực hiện yêu cầu
NHẬN tới URI đó. Nếu bạn muốn biết http://schema.org/Person và http://schema.org/birth- Date
nghĩa là gì, bạn cần tìm một tài liệu RDF ở đâu đó mô tả những điều đó.
nguồn.
Nếu không có ràng buộc về hypermedia thì sẽ không có quy tắc nào để tìm tài liệu mô tả. Bạn chỉ
cần lục lọi cho đến khi tìm thấy nó. Nhưng tài liệu đó thực sự quan trọng! Đó là cách duy nhất
để thu hẹp khoảng cách ngữ nghĩa. Không có nó, http://schema.org/ BirthDate chỉ là một chuỗi
ngắn, vô nghĩa.
Lược đồ RDF
Hiện tại, hãy bỏ qua câu hỏi về việc tìm kiếm tài liệu ma thuật đó. Tài liệu sẽ trông như thế
nào khi bạn tìm thấy nó? Tài liệu sẽ giải thích những chuỗi ngắn vô nghĩa đó. Có thể nói rằng
các URI http://schema.org/Person và http:// lược đồ.org/birthDate tương ứng gần đúng với quan
niệm hàng ngày của chúng ta về “người” và “ngày sinh”. Nó sẽ hoạt động như một hồ sơ, về nguyên
tắc không khác gì hồ sơ ALPS hoặc XMDP.
Cấu hình RDF đôi khi được gọi là từ vựng hoặc bản thể luận. Nó được viết bằng cách sử dụng một
loại siêu từ vựng gọi là Lược đồ RDF. Lược đồ RDF cho phép bạn sử dụng RDF để đưa ra các tuyên
bố về các loại tài nguyên, không chỉ các tài nguyên riêng lẻ.
Dòng thứ ba cho biết loại tài nguyên của http://schema.org/Person là rdfs:Class.
Điều đó có nghĩa là http://schema.org/Person không đại diện cho một đối tượng cụ thể trong thế
giới thực (một cá nhân). Nó tượng trưng cho một khái niệm (khái niệm về “con người”).
Các thuộc tính rdfs:label và rdfs:comment trỏ đến một số thông tin mà con người có thể đọc được
về khái niệm bí ẩn này. Người đọc tài liệu này sẽ biết rằng tài nguyên http://schema.org/Person
tương ứng với quan niệm hàng ngày của chúng ta về một
2. Bản thể luận RDF chính thức cho lược đồ.org nằm ở đây. Tôi ước gì tôi có thể trích dẫn trực tiếp từ tài liệu đó trong các ví dụ của
mình, nhưng nó sử dụng RDFa, phiên bản HTML của RDF và tôi không có chỗ để giải thích RDFa ở đây.
Vì vậy, tôi đã chuyển đổi một số phần của tài liệu đó sang định dạng Turtle dựa trên văn bản mà tôi sử dụng trong suốt chương này.
"người." Vì vậy, nếu loại tài nguyên khác là http://schema.org/Person, điều đó có nghĩa là tài
Nhưng cũng có một thành phần máy có thể đọc được đối với cấu hình Lược đồ RDF này: thuộc tính
rdfs:sub ClassOf . Điều này nói lên rằng mọi tài nguyên là http://schema.org/Person cũng là http://
của mình bằng cách xem mô tả RDF của URI đó , nằm ở vị trí thuận tiện trong cùng tệp với mô tả
của http://schema.org/Person:
...
<http://schema.org/Thing> một rdfs:Lớp
rdfs:label "Thứ"
rdfs:comment "Loại mặt hàng chung nhất."
Hóa ra http://schema.org/Thing chẳng có gì đặc biệt cả. Một kiểu phản cao trào.
Nhưng ít nhất bây giờ bạn biết rằng http://schema.org/Thing không đề cập đến bộ phim The Thing
của John Carpenter năm 1982, bản làm lại năm 2011 của nó, hay siêu anh hùng Marvel có tên The Thing.
Thế còn http://schema.org/birthDate thì sao ? Điều đó nghĩa là gì? Chà, đây là mô tả RDF của tài
nguyên đó , được phỏng theo cùng một tài liệu từ vựng giống như hai mô tả khác mà tôi vừa cho bạn
xem:
<http://schema.org/birthDate> và <rdf:Property> ;
rdfs:label "Ngày sinh" ;
rdfs:comment "Ngày sinh." ; rdfs:tên
miền <http://schema.org/Person> ; rdfs:range
<http://schema.org/Date> .
Những phần con người có thể đọc được trong mô tả này chỉ xác nhận những gì bạn đã nghi ngờ: rằng
http://schema.org/birthDate là một nguồn tài nguyên tương ứng với khái niệm “ngày sinh” trong thế
giới thực. Mối quan tâm thực sự ở đây là các phần mô tả mà máy có thể đọc được—tên miền và phạm
vi:
Hai dòng RDF/Rùa này nói rằng Ngày sinh là mối quan hệ giữa Người và Ngày. Hãy coi ngày sinh như
một hàm. Bạn đưa vào một người và bạn lấy ra một ngày—ngày sinh của người đó. Miền là đầu vào và
phạm vi là đầu ra .
Hai xác nhận có thể đọc được bằng máy này là những sợi dây nhỏ được ném qua khoảng cách ngữ nghĩa.
Gần như mọi thứ trong từ vựng RDF của lược đồ.org đều hiển nhiên một cách mù
quáng đối với con người. Nhưng để lập trình cho máy tính hiểu được những phần
từ vựng mà tôi đã chỉ cho bạn, bạn phải dạy cho máy tính bốn khái niệm khác
nhau: Người, Đồ vật, Ngày sinh và Ngày. Từ vựng của Schema.org chứa gần một
nghìn khái niệm và luôn được bổ sung thêm. Không ai có thể lập trình cho máy
tính để hiểu được tất cả chúng.
Đó là lý do tại sao các phần máy có thể đọc được trong từ vựng Lược đồ RDF—các thuộc tính như
subclassOf, miền và phạm vi—là quan trọng. Chúng cung cấp cho máy tính sự hiểu biết ở mức độ thấp về
ngữ nghĩa ứng dụng mà không cần sự hướng dẫn của con người. Một máy khách RDF không biết Ngày sinh
là gì có thể nhầm lẫn với kiến thức (xuất phát từ các thuộc tính miền và phạm vi ) rằng đó là một
Cấu hình ALPS và XMDP chủ yếu dựa vào các mô tả ngữ nghĩa ứng dụng mà con người có thể đọc được.
Điều này có nghĩa là họ dựa vào sức lao động của con người để biến những mô tả đó thành mã máy khách
đang hoạt động. Cấu hình Lược đồ RDF đưa nhiều ngữ nghĩa ứng dụng của API hơn vào dạng máy có thể
đọc được. Một phần mở rộng cho Lược đồ RDF có tên là OWL (mà tôi sẽ không đề cập tới) cho phép bạn
đưa ý tưởng này đi xa hơn nữa. Ước mơ là thay vì dạy máy tính của bạn hàng triệu khái niệm cụ thể,
bạn có thể dạy nó vài trăm khái niệm cơ bản và để nó tự tìm ra phần còn lại.
Cái giá phải trả là những lời giải thích trở nên rất phức tạp. Bạn có thể sử dụng Lược đồ RDF và OWL
để mô tả “ngày sinh” theo các khái niệm rất cơ bản. Nó sẽ xuất hiện kiểu như “ngày diễn ra sự kiện
trong đó một người thay đổi trạng thái từ không tồn tại sang tồn tại.”3 Đối với hầu hết các ứng
dụng, các tác giả khách hàng sẽ dễ dàng hơn chỉ cần viết một số mã xử lý ngày sinh theo cách họ muốn.
RDF rất tốt cho việc diễn đạt ngữ nghĩa ứng dụng theo các thuật ngữ mà máy có thể đọc được. Nhưng
bạn không thể xây dựng API RESTful chỉ dựa trên RDF, vì RDF sử dụng URI thay vì URL.
Không có gì đảm bảo rằng khách hàng có thể nhận được bản trình bày về bất kỳ tài nguyên nào mà họ
thấy được mô tả. Điều này làm cho hầu hết các ràng buộc Fielding không liên quan.
Tất nhiên, với tư cách là nhà thiết kế API, bạn có thể bỏ qua quy tắc đó. Bạn có thể khai báo rằng
tất cả các URI của bạn đều là URL và tất cả tài nguyên của bạn đều có biểu diễn. Tài nguyên của bạn
có thể phục vụ các tài liệu RDF tập trung vào việc mô tả chính chúng, thay vì mô tả các tài nguyên
khác có thể có hoặc không có phần trình bày. Tại thời điểm đó, bạn sẽ lấy lại được các ràng buộc
Fielding. Tất cả các URI trong biểu diễn RDF của bạn sẽ trở thành các liên kết hypermedia và khách
hàng của bạn có thể cảm thấy hài lòng khi theo dõi chúng.
Trường phái tư tưởng này được gọi là Dữ liệu được liên kết. Thuật ngữ này xuất phát từ một bài luận
năm 2006 của Tim Berners-Lee, trong đó ông xác định bốn nguyên tắc để đưa dữ liệu máy có thể đọc được
lên Web. Từ góc độ REST, các nguyên tắc này nới lỏng ràng buộc URI của RDF— họ nói rằng bạn có thể
coi URI là một URL—để tận dụng các ràng buộc Fielding.
Họ đưa triết lý Web ngữ nghĩa đến gần hơn với triết lý REST. Dưới đây là bốn nguyên tắc về Dữ liệu
3. Từ vựng BIO không đi xa đến thế, nhưng nó mô tả nguồn tài nguyên “sự kiện sinh nở”, http://purl.org/
vocab/bio/0.1/Birth, nơi tập hợp người được sinh ra, cha mẹ của họ, ngày tháng và địa điểm.
Theo thuật ngữ REST, điều này nói lên rằng URI xác định tài nguyên. Trong Chương 1, tôi gọi đây là
2. Sử dụng HTTP URI để mọi người có thể tra cứu những tên đó.
Điều này có hai phần. Trước tiên, bạn không nên xác định tài nguyên của mình bằng các URI như
Đúng là urn:isbn:9781449358063 là một cách tổng quát hơn nhiều để tham chiếu đến tài nguyên, nhưng
vì nó quá chung chung nên khách hàng không thể làm bất cứ điều gì với tham chiếu đó.
Thứ hai, nguồn lực phải có sự đại diện. Một ứng dụng khách gửi yêu cầu GET tới một URL sẽ nhận được
một số dữ liệu hữu ích. Một URL như http://vocab.org/vnd/ mamund.com/2013/numbers/primes có vẻ ổn,
cho đến thời điểm bạn gửi yêu cầu GET tới nó và gặp lỗi 404. Sau đó, bạn phát hiện ra rằng URL thực
sự là một URI. Nó không có đại diện. Có thể có một tài liệu kỳ diệu nào đó mô tả URI đó, nhưng chúc
3. Khi ai đó tra cứu URI, hãy cung cấp thông tin hữu ích bằng cách sử dụng các tiêu chuẩn (RDF*, SPARQL).
Một lần nữa, tài nguyên có đại diện. Máy khách gửi yêu cầu GET tới URL của tài nguyên sẽ nhận được
tài liệu ghi lại trạng thái hiện tại của tài nguyên.
Các tiêu chuẩn chính xác không thành vấn đề (tôi thậm chí còn không đề cập đến SPARQL trong cuốn
sách này). Điều quan trọng là bạn sử dụng một số tiêu chuẩn thay vì tạo ra một định dạng dữ liệu tùy
chỉnh. Bằng cách đó, khách hàng hiểu được tiêu chuẩn của bạn sẽ tự động biết cách xử lý dữ liệu bạn
cung cấp—ít nhất là ở mức cơ bản. Đây là chủ đề mà tôi đã đề cập xuyên suốt cuốn sách này: bạn nên
sử dụng định dạng siêu phương tiện hiện có thay vì xác định định dạng của riêng bạn.
4. Bao gồm các liên kết đến các URI khác. để họ có thể khám phá được nhiều điều hơn nữa.
Và cuối cùng, phần thưởng lớn: hạn chế về hypermedia. URI hiện là một URL, một liên kết mà khách
hàng có thể theo dõi để nhận thông tin đại diện. Đại diện đó sẽ chứa các liên kết khác và khách hàng
có thể theo dõi chúng để tiến gần hơn đến việc thực hiện bất kỳ mong muốn nào mà nó đã được lập
trình.
Nếu bạn muốn viết API dữ liệu được liên kết, tôi khuyên bạn nên sử dụng JSON-LD làm định dạng trình
bày thay vì RDF/XML hoặc RDF/Turtle. JSON-LD là một phiên bản tuần tự mới của RDF được thiết kế đặc
biệt để tạo các API giống với các API hypermedia khác ngày nay.
JSON-LD
Được mô tả trong: tiêu chuẩn mở đang được tiến hành, được xác định tại http://www.w3.org/TR/json-
ld/
• Ngữ nghĩa giao thức: điều hướng thông qua các liên kết GET
• Ngữ nghĩa ứng dụng: rất linh hoạt, nhưng mỗi tài liệu phải xác định một tài liệu riêng
Trong Chương 8, tôi đã trình bày JSON-LD dưới dạng định dạng hồ sơ. Tôi đã chỉ ra cách biểu diễn
JSON đơn giản…
HTTP/1.1 200 OK
Loại nội dung: application/json
…có thể được chuyển đổi thành tài liệu hypermedia bằng cách bổ sung “ngữ cảnh” JSON-LD:
HTTP/1.1 200 OK
Loại nội dung: application/ld+json
{
"@bối cảnh":
{
"n": "http://alps.io/schema.org/Person#name",
"photo_link": {
} }
Ngữ cảnh JSON-LD này giải thích mối quan hệ liên kết photo_link và bộ mô tả ngữ nghĩa n bằng cách
liên kết đến các giải thích. Tôi đã trình bày các phiên bản khác nhau của ngữ cảnh này: một phiên
bản được liên kết với cấu hình ALPS, một phiên bản được liên kết với tài liệu mà con người có thể
đọc được và một phiên bản sử dụng URI được mô tả bằng từ vựng RDF. Đây là một ví dụ khác sử dụng
{
"@bối cảnh":
{
"n": "http://schema.org/name",
"photo_link": {
"@id": "http://schema.org/image",
"@type": "@id" }
}
}
một tài liệu JSON đơn giản giải thích ngữ nghĩa ứng dụng của nó. Bạn sử dụng tiêu đề Liên kết để kết
nối tài liệu JSON với ngữ cảnh JSON-LD của nó:
Sẽ không chính xác lắm khi nói rằng JSON-LD là một định dạng hồ sơ. Việc biết rằng tài liệu JSON có
ngữ cảnh JSON-LD không chỉ cung cấp cho khách hàng một số thông tin bổ sung về ngữ nghĩa ứng dụng
của nó. Nó thay đổi hoàn toàn cách khách hàng xử lý tài liệu. Phân tích cú pháp tài liệu JSON mà
không cần xem ngữ cảnh và bạn sử dụng các quy tắc JSON và kết thúc bằng cấu trúc dữ liệu lồng nhau.
Phân tích cùng một tài liệu cùng với ngữ cảnh của nó và bạn sử dụng các quy tắc RDF và kết thúc bằng
Và JSON-LD không bị giới hạn ở vai trò tiện ích bổ sung này. Bất kỳ đối tượng JSON nào cũng trở thành
tài liệu JSON-LD nếu bạn thêm thuộc tính @context và phân phát nó dưới dạng application/ld+json.
Điều này có nghĩa là bạn có thể kết hợp bối cảnh JSON-LD với dữ liệu bạn đang phân phối và phân phối
HTTP/1.1 200 OK
Loại nội dung: application/ld+json
"liên_kết_ảnh":
{
"@id": "http://schema.org/image",
"@type": "@id"
}
}
}
Tại thời điểm này, JSON-LD trở thành định dạng hypermedia truyền thống. Tiêu đề Liên kết không còn
cần thiết nữa vì chỉ có một tài liệu. Vẫn rõ ràng rằng pho to_link là một liên kết hypermedia. Trên
thực tế, nó rõ ràng hơn trước vì tất cả thông tin đều ở một nơi.
JSON-LD | 275
Machine Translated by Google
Nhưng khi các định dạng biểu diễn phát triển, JSON-LD không có nhiều khả năng. Nhờ di sản RDF của nó,
JSON-LD có thể mô tả ngữ nghĩa ứng dụng rất chi tiết, nhưng ngữ nghĩa giao thức của nó rất hạn chế.
Máy khách Dữ liệu được Liên kết không thể làm gì khác ngoài việc đi theo các liên kết từ bit dữ liệu
này sang bit dữ liệu khác. Máy khách không thể thay đổi dữ liệu vì JSON-LD không có điều khiển siêu
phương tiện nào để kích hoạt các yêu cầu HTTP không an toàn.
Nếu bạn muốn sử dụng JSON-LD trong API của mình, tôi khuyên bạn cũng nên sử dụng tiện ích mở rộng có
tên Hydra.
Hydra
Được mô tả trong: tiêu chuẩn cá nhân đang được tiến hành tại http://www.markus-lanthaler.com/
hydra/
nghĩa ứng dụng: bắt nguồn từ JSON-LD; triển khai mẫu bộ sưu tập (“bộ sưu tập” và “tài nguyên”),
nhưng các bộ sưu tập không có ngữ nghĩa giao thức đặc biệt
Hydra là một bối cảnh JSON-LD bổ sung nhiều ngữ nghĩa giao thức vào JSON-LD. Bản thân JSON-LD chỉ cho
phép bạn chỉ định các liên kết (sử dụng "@type": "@id"), để được kích hoạt bằng các yêu cầu GET. Thêm
Hydra vào hỗn hợp và bạn có thể chỉ định hầu hết mọi yêu cầu HTTP.
Đây là tài liệu Hydra mô tả ngữ nghĩa ứng dụng và giao thức của API viết blog dọc theo dòng
{
"@context": "http://purl.org/hydra/core/context.jsonld", "@type":
"ApiDocumentation", "title":
"API blog", "description": "Bạn
gõ nó, chúng tôi đăng nó.", "entrypoint": "http://
example.com/api/", "supportedClasses": [
{
"@id": "#BlogDirectory",
"title": "Thư mục các blog",
"description": "Liên kết tới tất cả các
blog.", "supportedProperties": [
{
"@id": "#blogs",
"@type": "link",
"title": "Blog",
"description": "Các blog có sẵn.", "domain":
"#BlogDirectory", "range" :
"#Blog"
] },
{
"@id": "#Blog",
"@type": "Class",
"subClassOf": "Collection",
"title": "Blog",
"description": "Tập hợp các bài viết.",
"supportedOperations" : [
{
"@type": "CreatResourceOperation",
"phương thức":
"POST", "mong đợi": "#BlogPost"
}
] },
{
"@id": "#BlogPost",
"@type": "Class",
"title": "Bài
đăng", "description": "Một bài đăng
blog.", "supportedProperties": [
{
"@id": "#content",
"@type": "rdfs:Property",
"title": "Nội dung",
"description": "Nội dung của một bài đăng trên
blog.", "domain":
"#BlogPost ", "phạm
vi": "xsd:string" }
]
}
]
}
Một khách hàng hiểu Lược đồ JSON-LD và RDF có thể lấy được nhiều thông tin từ tài liệu
này. Nó có thể tìm hiểu về ba loại tài nguyên (http://example.com/youty‐
peit.jsonld#BlogDirectory, http://example.com/youtypeit.jsonld#Blog, và http://exam‐
ple.com/youtypeit .jsonld#BlogPost), mỗi tệp đều có mô tả mà con người có thể đọc được.
Ngay cả khi khách hàng không biết gì về Hydra, điều đó cũng đủ để tạo nên ý nghĩa của
việc trình bày. Đây là bản trình bày JSON-LD của trang chủ API, được cung cấp từ
http:// example.com/api/:
HTTP/1.1 200 OK
Loại nội dung: application/ld+json
{ "@bối cảnh": {
Hydra | 277
Machine Translated by Google
"blogs": "http://example.com/youtypeit.jsonld#blogs",
"Blog": "http://example.com/youtypeit.jsonld#Blog" },
"@id:"http:/ /example.com/api/",
"blogs":
[ { "@id": "/api/blogs/1", "@type": "Blog" },
{ "@id": "/api/blogs /2", "@type": "Blog" } ]
Có lẽ bạn đang thắc mắc thuộc tính blog đó có nghĩa là gì? Chà, @context nói rằng ngữ
nghĩa ứng dụng của nó được xác định tại http://example.com/youtypeit.jsonld#blogs. Đây
nó là:
{
"@id": "#blogs",
"@type": "link",
"title": "Blog",
"description": "Các blog có sẵn.", "domain":
"#BlogDirectory", "range" :
"#Blog"
}
Đó là danh sách các blog. Chính thức hơn, đó là một hàm mà các đầu ra (phạm vi) có thể
có đều có loại tài nguyên http://example.com/youtypeit.jsonld#Blog. Điều đó có nghĩa là
bit JSON này là mô tả của hai tài nguyên loại blog khác nhau:
"blog":
[ { "@id": "/api/blogs/1", "@type": "Blog" },
{ "@id": "/api/blogs/2", "@type": "Blog" }
]
Tất nhiên, đó không phải là mô tả nhiều. Bạn không biết gì về những tài nguyên này
ngoại trừ URI và loại ngữ nghĩa của chúng. Trong tài liệu RDF truyền thống, câu chuyện
sẽ kết thúc ở đây. Bạn sẽ không bao giờ học được điều gì khác về những nguồn tài nguyên
này trừ khi bạn tìm thấy mô tả tốt hơn về chúng nằm đâu đó.
Nhưng đây là tài liệu JSON-LD nên bạn biết nó tuân theo ràng buộc hypermedia. Bạn nên
thực hiện yêu cầu NHẬN tới /api/blogs/1 hoặc /api/blogs/2. Bạn biết rằng nếu bạn thực
hiện yêu cầu GET đó, bạn có thể mong đợi một biểu diễn đáp ứng ngữ nghĩa ứng dụng của
Blog.
Đến thời điểm này không cần phải có kiến thức gì về Hydra cả. Máy khách JSON-LD có thể
tạo yêu cầu GET cho trang chủ API, hiểu ngữ cảnh và tạo yêu cầu GET thứ hai tới /api/
blogs/2. Nó có thể so sánh cách trình bày mà nó nhận được với mô tả của loại tài nguyên
Blog và hiểu được ngữ nghĩa ứng dụng của “Blog” cụ thể này.
Nhưng một khách hàng biết về Hydra sẽ có lợi thế lớn ở đây. Nó hiểu một thuộc tính đặc
biệt được gọi là supportOperations. Trong bối cảnh này, supportOperations nói rằng
một loại tài nguyên Blog—hỗ trợ HTTP POST cũng như GET. Hãy xem xét lại phần này:
{
"@id": "#Blog",
...
"hoạt động được hỗ trợ": [
{
"@type": "CreatResourceOperation",
"phương thức":
"POST", "mong đợi":
"#BlogPost" }
]
}
Điều đó nói lên rằng khách hàng có thể tạo tài nguyên mới (thuộc loại BlogPost) bằng
cách thực hiện yêu cầu HTTP POST tới tài nguyên thuộc loại Blog. Phần nội dung thực thể
của yêu cầu phải là biểu diễn JSON-LD đáp ứng ngữ nghĩa ứng dụng của BlogPost .
Ngữ nghĩa ứng dụng của BlogPost là gì? Vâng, ngữ cảnh ban đầu nói rằng BlogPost có một
thuộc tính duy nhất, được gọi là nội dung, là một chuỗi (xsd:string):
{
"@id": "#BlogPost",
...
"supportProperties": [
{ "@id": "#content",
"@type": "rdfs:Property",
"title": "Nội dung",
"description": "Nội dung của một bài đăng trên
blog.", "domain": "#
BlogPost", "phạm vi": "xsd:string"
}
]
}
Kết hợp tất cả lại với nhau và khách hàng Hydra biết rằng họ có thể gửi yêu cầu POST
trông giống như thế này:
{ "@bối cảnh": {
"nội dung": http://www.example.com/youtypeit.jsonld#content" },
Hydra | 279
Machine Translated by Google
JSON-LD cung cấp cho nhà cung cấp API một cách để giải thích ngữ nghĩa ứng dụng của một tài liệu JSON có
vẻ bình thường. Ngữ cảnh JSON-LD cũng có thể giải thích ngữ nghĩa giao thức của tài liệu đó bằng cách cấp
cho khách hàng quyền tổng quát để thực hiện yêu cầu HTTP GET tới bất kỳ URI nào họ tìm thấy. Nhưng đó là
tất cả những gì nó đi. Bản thân JSON-LD chỉ có thể mô tả các chuyển đổi trạng thái an toàn.
Hydra còn tiến xa hơn nữa. Ngữ cảnh JSON-LD bao gồm các thuộc tính Hydra đặc biệt có thể cho khách hàng
biết rằng nó được phép thực hiện bất kỳ loại yêu cầu HTTP nào, không chỉ GET. Hydra có thể mô tả quá
trình chuyển đổi trạng thái không an toàn một cách chi tiết.
Nhìn chung, tôi sẽ so sánh bối cảnh Hydra với tài liệu WADL và tài liệu siêu dữ liệu OData, cả hai tài
liệu này tôi đã trình bày trong Chương 10. Những tài liệu này có xu hướng được sử dụng để xác định trước
các loại tài nguyên (Blog, BlogPost) , thay vì đại diện cho hành vi của các tài nguyên riêng lẻ trong
Hầu như bất kỳ API nào cũng sẽ có các loại tài nguyên riêng biệt và tất cả các tài nguyên thuộc một loại
nhất định sẽ có ngữ nghĩa giao thức và ứng dụng tương tự.
Nhưng có một sự cám dỗ mạnh mẽ là nhầm lẫn “loại ngữ nghĩa trừu tượng của tài nguyên” với “chi tiết triển
khai của một lớp trong mô hình dữ liệu của tôi”. Ngữ cảnh Hydra, tài liệu siêu dữ liệu OData và tài liệu
WADL cám dỗ các nhà phát triển API phía máy chủ tự động tạo từ vựng một lần dựa trên mô hình dữ liệu nội
Và có một vấn đề lớn hơn mà tôi đã đề cập ở Chương 9. Vì những tài liệu này không thay đổi thường xuyên
nên các nhà phát triển API phía máy khách có xu hướng coi chúng như tài liệu mô tả dịch vụ, có khả năng
cung cấp cái nhìn tổng quan hoàn chỉnh về API. ngữ nghĩa ứng dụng. Người dùng sẽ có xu hướng tạo mã máy
khách dựa trên ngữ cảnh Hydra—mã máy khách sẽ bị hỏng khi ngữ cảnh thay đổi.
Khi tôi viết bài này, tiêu chuẩn Hydra vẫn đang trong quá trình hoàn thiện, nhưng đó là lựa chọn tốt hơn
nhiều cho các API hypermedia dựa trên JSON so với JSON-LD đơn giản, vì nó có thể mô tả các chuyển đổi
trạng thái không an toàn. Chỉ cần đảm bảo rằng bạn không sử dụng nó theo cách làm mất đi lợi ích của ràng
URL và chúng phải có các biểu diễn hữu ích đằng sau chúng. Các URI như urn:isbn:9781449358063 rắc rối
Điều gì sẽ xảy ra nếu bạn từ chối thực hiện thỏa hiệp này? Bạn có thể đi được bao xa với một API sử dụng
chiến lược mô tả thuần túy? Đó là điều tôi muốn khám phá với phạm vi bao quát của mình về định dạng XRD
và hai tiêu chuẩn được xây dựng dựa trên định dạng đó: tài liệu siêu dữ liệu máy chủ web và WebFinger.
XRD là câu trả lời của chiến lược mô tả cho các định dạng XML và JSON đặc biệt được các API
ngày nay sử dụng. Tài liệu siêu dữ liệu máy chủ web giúp bạn có thể xây dựng API hypermedia
xung quanh các tài nguyên mà bạn không kiểm soát, các tài nguyên có thể không có đại diện nào cả.
Điều này có vẻ giống như một thủ thuật tiệc tùng vô nghĩa, nhưng WebFinger cho chúng ta thấy một trường hợp sử dụng thực tế.
XRD và JRD
Được xác định trong: RFC 6415 (JRD), tiêu chuẩn mở (XRD) •
• Ngữ nghĩa giao thức: điều hướng bằng liên kết GET •
XRD là định dạng tài liệu dựa trên XML truyền thống được thiết kế để mô tả các tài nguyên từ
bên ngoài. Không giống như RDF, XRD phân biệt giữa các bộ mô tả ngữ nghĩa, nằm trong thẻ
Việc này khá đơn giản khi bạn hiểu được chiến lược mô tả. Đây là mô tả XRD của một ô trong mê
cung Mê cung+XML:
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Subject>http://example.com/cells/M</Subject>
<Property type="http://alps.io/example/maze#title">
Hành lang vào </
Property>
<Link rel="http://alps.io/example/maze#east"
href="http://example.com/cells/N" />
<Link rel="http://alps.io/example /mê
cung#west" href="http://example.com/cells/L" />
</XRD>
Một lần nữa, việc tài nguyên được xác định bởi http://example.com/ cell/M có “tồn tại” hay
không không quan trọng (nghĩa là có biểu diễn). Đây chỉ là một tài liệu với một vài điều để
nói về tài nguyên đó.
RFC 6415 xác định một cách đơn giản để dịch tài liệu XRD thành đối tượng JSON. Kết quả được
gọi là JRD và được dùng dưới dạng application/jrd+json:
{ "subject": "http://example.com/cells/M",
"properties":
{ "http://alps.io/example/maze#title": "Lối vào Hành lang" }, "liên
kết" :
[ { "rel": "http://alps.io/example/maze#east",
] }
• Ngữ nghĩa giao thức: điều hướng bằng GET; khả năng tra cứu hạn chế với GET • Ngữ nghĩa
Tài liệu siêu dữ liệu máy chủ web là tài liệu XRD chứa toàn bộ mô tả cấp cao nhất của API. Nó
giống như mô tả được tìm thấy trong Tài liệu gia đình JSON (xem Chương 10). Phiên bản XRD của tài
liệu siêu dữ liệu máy chủ web phải có URI nổi tiếng /.well-known/host-meta. (Xem Chương 9 để biết
phần giới thiệu về URI nổi tiếng.) Nếu có phiên bản JRD của tài liệu đó, thì nó phải nằm dưới URI
Giống như bất kỳ tài liệu XRD nào, tài liệu siêu dữ liệu máy chủ web có thể bao gồm các thuộc
tính và liên kết. Các thuộc tính là các thuộc tính của toàn bộ API, chẳng hạn như phiên bản triển
khai máy chủ hiện tại. Các liên kết là các liên kết đến các tài nguyên đặc biệt quan trọng trong
API, chẳng hạn như các bộ sưu tập cấp cao nhất.
Liên kết XRD có thể có thuộc tính mẫu thay vì thuộc tính href . Điều này biến liên kết thành dịch
vụ tra cứu thư mục cho URI. Sau đây là một ví dụ đơn giản cho thấy dịch vụ tra cứu có thể hữu ích
Thẻ <Link> này cho biết rằng nếu khách hàng muốn tìm tuyên bố bản quyền cho bất kỳ tài nguyên
nào, cho dù nó được xác định bằng URI http: hay URI urn:isbn:, nó sẽ gửi yêu cầu GET và chuyển
URI vào mẫu có rel="copyright". Yêu cầu GET đó sẽ kích hoạt quá trình chuyển đổi trạng thái bản
quyền cho URI đã được chuyển vào. Bằng cách này, khách hàng có thể kích hoạt quá trình chuyển đổi
trạng thái cho URI không có đại diện! URI urn:isbn:9781449358063 không có đại diện, nhưng nếu bạn
được đại diện của một tài nguyên liên quan: thông tin bản quyền của cuốn sách.
Giá trị của thuộc tính mẫu giống với Mẫu URI nhưng không phải là Mẫu URI vì biến duy nhất bạn
được phép sử dụng là {uri}. Tài liệu siêu dữ liệu máy chủ web có thể sử dụng <Link> để liên kết
đến một tài nguyên cụ thể khác (sử dụng thuộc tính href ) và nó có thể liên kết với dịch vụ tra
với biến {uri} ), nhưng chỉ vậy thôi. Bạn không thể đặt biểu mẫu tìm kiếm chung vào tài liệu siêu
dữ liệu máy chủ web.
Đây là ví dụ mà các tác giả của RFC 6415 rõ ràng đã nghĩ đến:
Điều này cho khách hàng biết rằng nếu họ muốn mô tả XRD của một tài nguyên, họ có thể cắm URI của
nó vào mẫu và gửi yêu cầu GET tới URL kết quả. Mối quan hệ liên kết lrdd là liên kết được đăng ký
IANA tới mô tả XRD. (Nó được gọi là lrdd vì những lý do quá phức tạp và buồn tẻ để đi sâu vào đây.)
Tài liệu siêu dữ liệu máy chủ web hiện là tài liệu XRD cho bạn biết cách tra cứu các tài liệu XRD
khác. Bạn có thể không bao giờ có được bản trình bày của URI, nhưng tài liệu siêu dữ liệu của máy
chủ web có thể giúp bạn tìm thấy nhiều mô tả khác nhau về URI đó.
WebNgón tay
Giao thức WebFinger chỉ là tên gọi cho việc sử dụng các tài liệu JRD để tra cứu thông tin về tài
khoản người dùng. Một tài khoản có thể được xác định bằng địa chỉ email, sử dụng acct: lược đồ
URI:4
tài khoản:jenny@example.com
Hoặc một tài khoản có thể được xác định bằng một http: URL, có thể là một URL được quản lý bởi một
http://openid.example.com/users/omjennyg
Một khách hàng thực hiện yêu cầu WebFinger bằng cách gửi yêu cầu GET tới việc chuyển URI tới tài
Máy chủ sẽ phản hồi kèm theo mô tả JRD của tài khoản người dùng. Mô tả này được cho là bao gồm
một thuộc tính JSON bổ sung được gọi là chủ đề, cung cấp URI của tài nguyên được mô tả:
4. Được xác định trong Internet-Draft “draft-ietf-appsawg-acct-uri,” như tôi đã đề cập trước đó.
HTTP/1.1 200 OK
Loại nội dung: application/jrd+json
Đúng thế đấy. Định dạng tệp JRD thực hiện hầu hết công việc và lược đồ acct: URI thực hiện
hầu hết mọi việc khác. Điểm duy nhất của WebFinger là thuộc tính chủ đề và mẫu URI nổi
tiếng, /.well-known/webfinger?resource={uri}.
Đây là một ví dụ hoàn hảo về tình huống trong đó mô tả tài nguyên hoạt động tốt hơn biểu
diễn tài nguyên. Khi một người đăng ký tài khoản trên trang web của bạn, bạn có thể nhận
dạng người đó bằng địa chỉ email hoặc URL OpenID của cô ấy. URL OpenID có phần đại diện nhưng
có thể bạn không kiểm soát máy chủ OpenID nên bạn không thể thay đổi phần đại diện của nó.
Một địa chỉ email không có đại diện nào cả! Tuy nhiên, WebFinger cho phép bạn xuất bản các
mô tả về tài khoản người dùng của mình. Bạn có thể nói bất cứ điều gì bạn muốn nói về những
tài khoản đó bằng cách chú thích tài khoản tương ứng: URI.
Tôi đã tập trung vào các từ vựng có thể hữu ích trong các API hướng tới người tiêu dùng. Hầu
hết các từ vựng thực sự nặng nề đều được sử dụng trong các ứng dụng khoa học hoặc y tế, không
phải để mô tả ngữ nghĩa của các tài liệu được cung cấp trên Web. Kiểm tra các ontology NGỌT
NGÀO cho một vốn từ vựng rất lớn được thiết kế để sử dụng khoa học.
những thứ mà con người có thể muốn tìm kiếm trực tuyến
Trước đó trong cuốn sách này, tôi đã trình bày các khái niệm được xác định bởi lược đồ.org—
Person, Creati veWork, v.v.—dưới dạng các mục vi dữ liệu HTML. Đó là cách chúng được trình
bày trên trang web Schema.org. Nhưng đằng sau hậu trường, những khái niệm đó được xác định
bằng từ vựng RDF có thể đọc được bằng máy. Đó là từ vựng tôi đã tham khảo trong suốt bài viết này
cùng vốn từ vựng RDF đó để tạo ra các phiên bản ALPS của tất cả các mục vi dữ liệu Schema.org cho
Nếu đang sử dụng RDF hoặc JSON-LD, bạn có thể tham khảo từ vựng RDF của lược đồ khi mô tả tài nguyên.
Điều này cho phép bạn nói về tất cả những điều mà Schema.org nói đến bằng cách sử dụng chiến lược mô
So sánh việc sử dụng vi dữ liệu Schema.org trong biểu diễn HTML của một tài nguyên…
…với việc sử dụng từ vựng RDF của lược đồ.org để mô tả một tài nguyên không có đại diện:
Tất nhiên, bạn không bị giới hạn trong việc mô tả mọi người. Bạn có thể sử dụng bất kỳ khái niệm nào
trong số gần 1.000 khái niệm được mô tả trong từ vựng RDF của Schema.org—miễn là Schema.org hiểu các
BÓNG ĐÁ
và tổ chức
FOAF là bản thể luận Lược đồ RDF nổi tiếng nhất. Đó là một tiêu chuẩn công nghiệp không chính thức để
Đây là cách thể hiện tên và ngày sinh của một người5 trong RDF/Turtle, sử dụng từ vựng FOAF:
vocab.org
Đây là trang lưu trữ các tài liệu Lược đồ RDF, được duy trì bởi Ian Davis. Nó giống như
sổ đăng ký Alps.io của riêng tôi cho các tài liệu ALPS. Bộ sưu tập mang tính chiết trung
và bao gồm từ vựng BIO mà tôi đã đề cập trong phần chú thích trước đó, cũng như từ vựng
để mô tả các loại rượu whisky.
Theo chính sách, vocab.org cũng cho phép mọi người yêu cầu các URI vùng tên bắt đầu bằng
http://vocab.org/vnd/. Điều này có nghĩa là tôi có thể xuất bản tài liệu RDF mô tả tài
nguyên có URI http://vocab.org/vnd/mamund.com/2013/my-wonderful-resource. Tôi không kiểm
soát vocab.org và tôi không được phép tải tệp lên đó, vì vậy tài nguyên đó sẽ không bao
giờ có đại diện. Nhưng tôi sở hữu URI đó và tôi có thể mô tả nó theo cách tôi muốn.
Chương này và cuộc sống nói chung sẽ đơn giản hơn nếu có thể bỏ qua chiến lược mô tả.
Nhờ Dữ liệu được Liên kết, bạn có thể làm được điều đó! Phong trào Dữ liệu được Liên kết
cho rằng tốt hơn nên sử dụng RDF theo cách đáp ứng các ràng buộc Fielding. Chỉ cần xuất
bản từ vựng Lược đồ RDF của bạn lên Web và đảm bảo bạn chỉ sử dụng nó để mô tả các tài
nguyên cũng tồn tại trên Web.
Ưu điểm của Dữ liệu được liên kết là khá lớn. Lược đồ RDF và OWL mạnh hơn nhiều so với
ALPS khi mô tả ngữ nghĩa ứng dụng theo cách máy có thể đọc được. Và bạn không cần phải
từ bỏ các ràng buộc Fielding để tận dụng những công nghệ này.
Nhưng tôi không thể giả vờ rằng Dữ liệu được Liên kết là toàn bộ câu chuyện. Web ngữ
nghĩa có lịch sử lâu đời hơn nhiều so với Dữ liệu được liên kết và ngay cả hiện nay,
không phải ai cũng tham gia vào nhóm Dữ liệu được liên kết. Khi sử dụng công nghệ Web ngữ
nghĩa, bạn sẽ gặp rất nhiều tài liệu có URL hóa ra là URI. Tôi không nghĩ bạn nên tạo
thêm những tài liệu này, nhưng để xử lý những tài liệu đã tồn tại, bạn cần hiểu ý nghĩa
của chúng. Chúng là những mô tả về các tài nguyên không có đại diện.
CHƯƠNG 13
Giao thức ứng dụng ràng buộc1 là giao thức được thiết kế để sử dụng trong các môi trường nhúng
tiêu thụ điện năng thấp như hệ thống tự động hóa gia đình. CoAP được lấy cảm hứng từ HTTP và có
thể được sử dụng để xuất bản API RESTful dựa trên siêu phương tiện, nhưng đó là một giao thức
rất khác với HTTP. CoAP mang kiến trúc giống như web đến một môi trường có nhiều hạn chế: một
“Internet of Things” trong đó rất nhiều máy tính nhỏ, giá rẻ giao tiếp qua mạng dung lượng thấp.
CoAP được thiết kế để tồn tại với những hạn chế nghiêm trọng về mức tiêu thụ điện, băng thông
mạng và sức mạnh xử lý. Thế giới của nó giống với ARPAnet của những năm 1970 hơn là mạng lưới mà
mọi người yêu thích ngày nay. Yêu cầu và phản hồi của CoAP rất nhỏ. Trên mạng chạy qua đường dây
điện gia đình, tin nhắn CoAP không được lớn hơn khoảng 1.024 byte. Trên mạng không dây công suất
Nhưng về mặt bố trí mạng, những môi trường này trông rất giống World Wide Web.
Không có một “nhà cung cấp API” nào phục vụ nhiều khách hàng tương tự. Thay vào đó, các thiết bị
từ nhiều nhà sản xuất khác nhau được đặt vào cùng một phòng, dường như là ngẫu nhiên.
Một số trong số họ có dữ liệu để cung cấp. Một số có khả năng khiến mọi việc xảy ra trong thế
giới thực. Rất hiếm khi một trong những thiết bị này có thể thu hút được sự chú ý của con người
Các thiết bị này phải định vị lẫn nhau qua mạng, tìm hiểu khả năng của nhau và tìm ra cách làm
việc cùng nhau, tất cả đều không có hoặc có rất ít sự hướng dẫn từ người lắp đặt thiết bị. Đó là
sự hỗn loạn hoàn toàn. Trong môi trường phi tập trung hoàn toàn này, cũng như trên Web, chiến
lược dựa trên hypermedia là chiến lược duy nhất có cơ hội hoạt động.
1. Một tiêu chuẩn mở đang được phát triển với tên gọi Internet-Draft “draft-ietf-core-coap”.
287
Machine Translated by Google
cách hoạt động của một yêu cầu HTTP thông thường. Máy khách mở kết nối TCP đến
máy chủ, gửi yêu cầu và chờ phản hồi qua cùng kết nối đó. CoAP được thiết kế để
hoạt động trên UDP, một giao thức chị em với TCP nhưng hoàn toàn không hỗ trợ
kết nối. Máy khách CoAP gửi tin nhắn yêu cầu đến máy chủ và sau đó thực hiện
công việc của mình. Khách hàng không biết khi nào tin nhắn phản hồi sẽ đến, nếu có.
Dưới đây là một thông báo yêu cầu mẫu được lấy từ tiêu chuẩn CoAP:
CON [0xbc90]
NHẬN /nhiệt độ
(Mã thông báo 0x71)
Tôi cần nói rõ rằng đây không phải là thông báo CoAP thực sự. Đây là phiên bản
tin nhắn mà con người có thể đọc được mà tôi đã định dạng để trông giống HTTP
nhất có thể. Thông báo thực sự được gửi qua UDP được đóng gói thành định dạng nhị
phân mà con người gần như khó hiểu: CON trở thành số nguyên 2 bit 00, GET trở
Thông báo yêu cầu có ý nghĩa gì? NHẬN /nhiệt độ sẽ có ý nghĩa đối với bạn từ HTTP. CoAP
định nghĩa bốn phương thức HTTP cơ bản (GET, POST, PUT và DE-LETE), mặc dù ngữ nghĩa của
CON là viết tắt của “Confirmable”, có nghĩa là thông báo này yêu cầu thông báo xác nhận
từ máy chủ (tôi sẽ nói thêm về điều này ở phần sau).
Số thập lục phân 0xbc90 là “ID tin nhắn”, sẽ được sử dụng trong tin nhắn xác nhận đó. Nếu
không có ID thông báo, ứng dụng khách thực hiện hai yêu cầu GET và nhận được hai phản hồi
sẽ không biết phản hồi nào sẽ phù hợp với yêu cầu nào.
Số thập lục phân 0x71 là “mã thông báo”. Một yêu cầu CoAP có thể kích hoạt một số phản
hồi và mã thông báo được sử dụng trong mọi phản hồi chứ không chỉ trong xác nhận ban đầu.
Phản hồi được gửi sau khi xác nhận sẽ có ID tin nhắn mới nhưng chúng sẽ được gắn với yêu
cầu ban đầu bằng mã thông báo.
Đây là phiên bản mà con người có thể đọc được của thông báo xác nhận.
ACK [0xbc90]
2.05 Nội dung
Một lần nữa, tôi định dạng thông báo này giống với HTTP. Nó thực sự không
giống như thế này. Một thông báo CoAP thực sự được đóng gói thành định
dạng nhị phân chặt chẽ. Ví dụ: loại phương tiện application/json được
biểu thị bằng chuỗi bit 8 bit 00110010.
• “ACK” có nghĩa là tin nhắn này xác nhận đã nhận được tin nhắn trước đó (tin nhắn CON mà tôi
đã cho bạn xem trước đó, với ID tin nhắn 0xbc90 và Mã thông báo 0x71).
• Dòng 2.05 Nội dung là mã trạng thái, tương đương với 200 OK của HTTP. • Định
dạng nội dung là một tùy chọn CoAP, phục vụ cùng mục đích như tiêu đề HTTP. Tùy chọn Content-
Format thực hiện công việc của tiêu đề Content-Type của HTTP .
• Chuỗi 22,5 C là tải trọng, cái mà HTTP gọi là “phần thân thực thể”.
Yêu cầu và phản hồi là những tin nhắn hoàn toàn khác nhau. Chúng không chia sẻ kết nối TCP theo
cách mà yêu cầu và phản hồi HTTP thực hiện. Chúng được kết nối bằng dữ liệu tìm thấy trong chính
được đặt tên theo một phương thức HTTP: GET, POST, PUT và DELETE. Các phương thức CoAP không
hoàn toàn giống với các phương thức HTTP tương ứng, nhưng chúng có các thuộc tính cơ bản giống
CoAP xác định một chút ngữ nghĩa giao thức bổ sung—loại thông báo—để giải quyết thực tế là các
yêu cầu và phản hồi CoAP được truyền trong các thông báo riêng biệt. Mỗi tin nhắn là một trong
• Một bản tin có thể xác nhận (CON) cần có một bản tin Xác nhận (ACK). Máy khách sẽ tiếp tục
gửi lại tin nhắn CON cho đến khi nhận được tin nhắn ACK có cùng ID tin nhắn.
• Một tin nhắn không thể xác nhận (NON) không yêu cầu một tin nhắn xác nhận (ACK). Chỉ những
yêu cầu an toàn (nghĩa là các yêu cầu GET) mới được thực hiện không thể xác nhận. • Một tin
nhắn xác nhận (ACK) thừa nhận rằng một tin nhắn trước đó đã được gửi lại
• Điều đó trái ngược với tin nhắn đặt lại (RST), xác nhận tin nhắn trước đó nhưng cho biết
rằng người nhận không thể xử lý tin nhắn đó. Người nhận có thể đã khởi động lại và
mất bối cảnh cần thiết hoặc có thể nó đã tạm thời rời khỏi mạng và bỏ lỡ tin nhắn
trước đó.
Về cơ bản, các loại thông báo này tạo lại cấu trúc phản hồi yêu cầu của HTTP. Thông báo
CON cộng với thông báo ACK tương đương với yêu cầu và phản hồi HTTP. Một máy khách gửi
tin nhắn CON và không nhận được xác nhận sẽ gửi lại tin nhắn CON, giống như một máy khách
HTTP gửi yêu cầu GET và không nhận được phản hồi nào sẽ gửi lại yêu cầu đó.
Nhưng có hai tính năng thú vị của CoAP hoàn toàn không có trong HTTP. Một (phản hồi bị
trì hoãn) dựa trên thực tế là một yêu cầu CoAP có thể kích hoạt một số phản hồi.
Cái còn lại (tin nhắn multicast) tận dụng một tính năng mà HTTP không thể sử dụng vì TCP
không hỗ trợ nó.
Phản hồi thứ hai này không phải là tin nhắn ACK. Đó là tin nhắn CON hoặc tin nhắn NON.
Máy chủ đang đảo ngược tình thế với máy khách. Tin nhắn thứ ba có ID tin nhắn khác với
tin nhắn CON ban đầu, nhưng nó sử dụng lại mã thông báo, vì vậy khách hàng ban đầu biết
rằng đó là phản hồi cho tin nhắn CON ban đầu.
Tình huống tương tự như việc mua một cuốn sách từ hiệu sách trực tuyến. Bạn gửi tin nhắn
CON và cửa hàng ngay lập tức gửi cho bạn biên nhận qua email (tin nhắn ACK), xác nhận
việc mua hàng của bạn. Nhưng bản thân cuốn sách sẽ không đến trong vài ngày tới. Bạn có
thể phải ký để nhận hàng (trả lời tin nhắn CON của máy chủ bằng tin nhắn ACK) hoặc người
vận chuyển thư có thể để cuốn sách ở trước hiên nhà của bạn (sách sẽ là tin nhắn KHÔNG).
Dù bằng cách nào, bạn sẽ nhận được sách của mình cùng với biên nhận (mã thông báo) liên
kết cuốn sách với đơn đặt hàng ban đầu của bạn (thông báo CON ban đầu của bạn).
HTTP xác định mã phản hồi (202, Được chấp nhận) hoạt động giống như thế này, nhưng HTTP
xác định không có cách nào để máy chủ liên lạc lại với máy khách sau khi xử lý xong tin
nhắn được “chấp nhận”. Vào thời điểm điều đó xảy ra, kết nối TCP đã bị đóng. Có nhiều
cách để giải quyết vấn đề này (tôi sẽ đề cập đến chúng khi nói về Được chấp nhận trong
Phụ lục B), nhưng không có giải pháp nào được xác định rõ ràng. Với CoAP, giải pháp được
tích hợp vào giao thức.
bộ. TCP không hỗ trợ phát đa hướng, vì vậy bạn thực sự không thể thực hiện việc này với HTTP.
Trường hợp sử dụng điển hình cho tính năng phát đa hướng CoAP (và cho CoAP nói chung) là tự động hóa
tại nhà. Trong trường hợp này, bộ điều nhiệt, tủ lạnh, tivi, công tắc đèn và các thiết bị gia dụng
khác có bộ xử lý nhúng giá rẻ giao tiếp qua mạng năng lượng thấp cục bộ. Khi bạn cắm một thiết bị
mới, nó sẽ phát hiện các máy tính khác trên mạng, khám phá khả năng của chúng thông qua việc trao đổi
Điều này cho phép các thiết bị của bạn điều phối hoạt động của chúng mà không cần bạn nhập trực tiếp.
Khi bạn bật lò nướng, hệ thống kiểm soát khí hậu có thể nhận thấy sự kiện này và giảm nhiệt độ trong
bếp. Bạn có thể rút điện thoại di động ra, lấy danh sách tất cả các đèn trong phòng hiện tại của bạn
và giảm độ sáng đèn thông qua điện thoại mà không cần phải đi tới công tắc đèn.
Trường hợp sử dụng tự động hóa gia đình đã tồn tại hơn 50 năm và cá nhân tôi nghĩ đó là một giấc mơ
viển vông, nhưng có những tình huống khác mà việc khám phá đa hướng ít sến hơn rất nhiều. Multicast
có thể cho phép một điện thoại di động nói chuyện với tất cả các điện thoại khác trong phòng.
Nó có thể cho phép một nhóm thiết bị khoa học chia sẻ kết quả đọc hoặc kết nối các thiết bị ngoại
Bất cứ khi nào có nhiều máy tính nhỏ ở cùng một nơi, CoAP và UDP multicast cho phép chúng khám phá
lẫn nhau và tìm ra cách chúng có thể hợp tác. Các nguyên tắc hoạt động là tính không trạng thái, khả
năng định địa chỉ và các thông điệp tự mô tả: các nguyên tắc cốt lõi của REST.
thuần túy • Ngữ nghĩa giao thức: điều hướng và tìm kiếm với GET •
Tất nhiên, REST không chỉ là giao thức truyền tải. REST hoạt động thông qua việc trao đổi các biểu
diễn siêu phương tiện và các biểu diễn siêu phương tiện có xu hướng
khá lớn. Bạn không thể gửi các biểu diễn HTML hoặc Collection+JSON khi toàn bộ phản hồi của bạn phải vừa
với 80 hoặc 1024 byte.2 HTTP có thể nén các biểu diễn
để tiết kiệm băng thông, nhưng việc nén sẽ không giúp ích gì ở đây. Cảm biến ánh sáng có thể không có đủ
khả năng xử lý để giải nén bản trình bày trong thời gian hợp lý, chưa nói đến việc phân tích tài liệu
được giải nén. Nó có thể không có đủ bộ nhớ để lưu trữ toàn bộ tài liệu. Đó là lý do tại sao các nhà phát
triển CoAP đã thiết kế một định dạng hypermedia mới dành riêng cho các ứng dụng nhúng: Định dạng Liên kết
CoRE.
Đây là bản trình bày Định dạng Liên kết CoRE của một ô trong trò chơi mê cung ở Chương 5.
</cells/M>;rel="current";rt="http://alps.io/example/maze#cell",
</cells/N>;rel="east";rt="http:/ /alps.io/example/maze#cell",
</cells/L>;rel="west";rt="http://alps.io/example/maze#cell",
<http://alps. io/example/maze>;rel="profile"
Có bốn liên kết, mỗi liên kết có thuộc tính rel . Ba trong số các liên kết (hiện tại,
phía tây và phía đông) trỏ đến các ô trong mê cung (ô). Liên kết thứ ba (hồ sơ) trỏ
đến một số loại hồ sơ giải thích ý nghĩa của hiện tại, đông, tây và ô .
Không giống như tin nhắn CoAP, tài liệu ở Định dạng liên kết CoRE có thể đọc được. Nó không phải là một
định dạng nhị phân. Thay đổi duy nhất tôi thực hiện đối với phần trình bày này là thêm một dòng mới sau
mỗi liên kết để nó phù hợp với trang. Định dạng liên kết CoRE có thể chứa nhiều siêu phương tiện vào một
kilobyte mà không làm mất hoàn toàn khả năng đọc của con người.
Định dạng liên kết CoRE mô tả một liên kết sử dụng cú pháp tương tự như tiêu đề HTTP liên kết .
RFC 6690 xác định một số tham số mở rộng, đặc biệt là rt chứa URI cho biết loại ngữ nghĩa trừu tượng (xem
Chương 12) của tài nguyên ở đầu bên kia của liên kết:
</cells/N>;rel="east";rt="http://alps.io/example/maze#cell"
RFC 6690 cũng đề xuất một số kỹ thuật tùy chọn để gửi truy vấn tìm kiếm đến tài nguyên CoAP và nhận lại
phản hồi ở Định dạng liên kết CoRE. Điều này cung cấp cho loại phương tiện định dạng liên kết/ ứng dụng
một số tính năng tương tự như các tính năng có trong Bộ sưu tập +JSON, OData hoặc bất kỳ cách triển khai
Nhưng không có chỗ trống cho dữ liệu trong tài liệu Định dạng Liên kết CoRE. Định dạng liên kết CoRE là
hypermedia ở dạng thuần túy nhất. Nó chỉ có thể đại diện cho sự chuyển đổi trạng thái. Dữ liệu thực—ví
dụ: chỉ số công cụ, số liệu thống kê và thông báo mà con người có thể đọc được—phải được cung cấp ở một
2. “Draft-ietf-core-block” Internet-Draft sẽ cho phép phân chia một lượng lớn thông tin đại diện thành một số tin nhắn
CoAP. Điều này sẽ giúp ích rất nhiều, nhưng việc xây dựng API kiểu web truyền thống xung quanh tính năng này sẽ rất
kém hiệu quả.
CoAP rất khác với HTTP nhưng kiến trúc của nó là RESTful. Hệ thống CoAP tuân theo ràng buộc không trạng thái. Trên
thực tế, nó không có trạng thái hơn HTTP, vì yêu cầu và phản hồi của nó không được liên kết với nhau bằng kết nối
TCP. CoAP xác định ngữ nghĩa giao thức tương tự (nhưng không giống) HTTP. Định dạng Liên kết Core không thể biểu
thị dữ liệu, nhưng đó là định dạng siêu phương tiện thực sự có nhiều điều khiển siêu phương tiện hơn HAL.
Thiết bị CoAP có thể kết nối với mạng, gửi tin nhắn phát đa hướng UDP để xem có ai khác ở xung quanh và bắt đầu
khám phá những gì các thiết bị khác cung cấp—tất cả mà không cần bất kỳ sự tương tác nào của con người. Tính linh
hoạt này có được nhờ hạn chế về siêu phương tiện của REST và đó là giải pháp thực tế duy nhất cho giấc mơ lâu đời
Một chiếc tủ lạnh muốn nói chuyện với lò vi sóng của bạn không thể kén chọn về loại lò vi sóng bạn đã lắp đặt.
Theo suy nghĩ của tôi, tình huống này trông giống như toàn bộ thế giới API. Chúng ta sống trong một ngôi nhà
(Internet) có hàng nghìn thiết bị có thể lập trình (API) hữu ích nhưng ít người biết đến.
REST là về việc làm cho các thiết bị đó hoạt động cùng nhau với sự tham gia tối thiểu của con người-
tâm trí.
Thành công có nghĩa là đồng ý về ngữ nghĩa ứng dụng. Thiết bị và API nên sử dụng những từ giống nhau khi nói về
những điều giống nhau. Nó cũng có nghĩa là quảng cáo ngữ nghĩa giao thức của chúng tôi. Mọi “thiết bị” đều phải
giải thích chức năng của nó, không phải trong một cuốn sách hướng dẫn đầy bụi bặm được cất trong một cặp mà phải
trực tuyến, bằng những thuật ngữ mà một “thiết bị” khác có thể hiểu được. Điều này có vẻ giống như một giấc mơ viển
vông nhưng đó là cách duy nhất để quản lý sự phức tạp của tất cả những thứ chúng tôi đã tạo ra.
PHỤ LỤC A
Mã trạng thái
Mã trạng thái HTTP là một số có ba chữ số được đính kèm với phản hồi HTTP. Đó là một chút ngữ
nghĩa về giao thức cho phép khách hàng biết, ở mức cơ bản nhất, điều gì đã xảy ra khi máy chủ
cố gắng xử lý yêu cầu. 41 mã phản hồi HTTP được xác định trong đặc tả HTTP tạo thành một tập
hợp ngữ nghĩa giao thức cơ bản mà bất kỳ API nào cũng có thể sử dụng.
Ngoài các chuyển hướng HTTP và trang lỗi “404 Not Found” nổi tiếng, chúng tôi không thực sự sử
dụng mã trạng thái trên World Wide Web. Con người tìm hiểu điều gì đã xảy ra với một yêu cầu
bằng cách đọc nội dung thực thể được dùng như một phần của phản hồi chứ không phải bằng cách
tra cứu mã số trong tiêu chuẩn HTTP. Khi bạn điền biểu mẫu trên một trang web nhưng quên điền
một trong các trường bắt buộc, máy chủ sẽ gửi lại thông báo lỗi nhưng mã phản hồi liên quan đến
Tốt rồi. Bạn thậm chí không nhìn thấy mã phản hồi. Bạn đọc thông báo lỗi và khắc phục sự cố.
Nhưng một API hoạt động theo cách đó sẽ nói dối khách hàng của nó! Các chương trình máy tính
rất giỏi tra cứu mã số nhưng lại rất tệ trong việc hiểu văn xuôi. Khi phân phát mã trạng thái
200 theo điều kiện lỗi, bạn phải viết thêm tài liệu giải thích rằng trong API của mình, OK
không nhất thiết có nghĩa là OK. Tài liệu bổ sung đó có nghĩa là người dùng của bạn sẽ phải làm
Do đó, trong thế giới API, mã phản hồi HTTP trở nên rất quan trọng. Chúng cho khách hàng biết
cách xem tài liệu trong phần thân thực thể—dù đó là một bản trình bày hay một thông báo lỗi—
hoặc phải làm gì nếu khách hàng không thể hiểu được phần thân thực thể. Máy khách (hoặc trung
gian giữa máy chủ và máy khách, như proxy hoặc tường lửa) có thể tìm hiểu yêu cầu HTTP diễn ra
như thế nào, chỉ bằng cách xem một vài byte đầu tiên của phản hồi.
Điều đó có nghĩa là một số mã trạng thái HTTP hoàn toàn vô dụng. Một số chỉ hữu ích trong những
trường hợp rất hạn chế và một số chỉ có thể phân biệt được với nhau bằng cách tách tóc cẩn
thận. Đối với những người đã quen với World Wide Web (đó là tất cả chúng ta), sự đa dạng của
295
Machine Translated by Google
Trong phụ lục này, tôi đưa ra giải thích ngắn gọn về từng mã trạng thái, kèm theo các mẹo về thời điểm
sử dụng nó trong API của bạn và ý kiến cá nhân của tôi về tầm quan trọng của nó đối với thiết kế API.
Nếu khách hàng phải làm điều gì đó cụ thể để nhận được mã phản hồi nhất định, tôi sẽ giải thích đó là gì.
Tôi cũng liệt kê các tiêu đề phản hồi HTTP nào và loại nội dung thực thể nào mà máy chủ phải gửi cùng
với mã phản hồi. Đây là phụ lục dành cho nhà phát triển API nhưng cũng dành cho tác giả ứng dụng khách,
Giống như các mối quan hệ liên kết và các loại phương tiện, IANA giữ một sổ đăng ký chính thức về mã
trạng thái HTTP . Ở đây, “chính thức” về cơ bản có nghĩa là “được xác định trong RFC”. Trong phụ lục
này, tôi sẽ đề cập đến tất cả 41 mã được đề cập trong RFC 2616, mặc dù một số mã trong số đó (chủ yếu
là các mã liên quan đến proxy) nằm ngoài phạm vi của cuốn sách này một chút. Tôi cũng sẽ đề cập đến một
số mã trạng thái được xác định trong các RFC khác, đặc biệt là RFC 6585, được đặt tên thích hợp là “Mã
trạng thái HTTP bổ sung”.
Tôi sẽ không đề cập đến các mã trạng thái lấy cảm hứng từ HTTP của CoAP (Không tìm thấy 4.04) hoặc các
mã trạng thái HTTP được xác định bởi các tiện ích mở rộng như WebDAV. Tôi cũng không bao gồm các mã
trạng thái được giới thiệu bởi việc triển khai máy chủ web nhưng không được xác định chính thức ở bất
kỳ đâu. Chúng bao gồm 509 (Vượt quá giới hạn băng thông) và nhiều mã báo cáo lỗi nội bộ của nginx, như
đưa ra lời giải thích mà con người có thể đọc được về mã trạng thái HTTP. Đừng quên những điều này! Bạn
có thể sử dụng chúng để thêm thông tin chi tiết dành riêng cho API vào mã trạng thái chung như 400 (Yêu
cầu không hợp lệ). Không cần phải phát minh ra một định dạng trình bày mới (hoặc tệ hơn là mã trạng
thái mới) để truyền tải thông tin lỗi chi tiết. Nếu định dạng trình bày của bạn có chỗ để báo cáo lỗi,
như cách Collection+JSON thực hiện, bạn có thể không cần tài liệu chi tiết về vấn đề.
Hãy nhớ rằng, báo cáo lỗi chi tiết không phải là cái cớ để đưa ra 200 (OK) khi có điều gì đó không ổn.
Ý nghĩa của việc trình bày của bạn phải luôn nhất quán với mã trạng thái HTTP của bạn.
Họ mã trạng thái
Chữ số đầu tiên của mã trạng thái HTTP là dấu hiệu rất chung chung về cách thực hiện yêu cầu. Đặc tả
HTTP xác định năm họ mã trạng thái bằng cách sử dụng các chữ số ban đầu từ 1 đến 5. Tôi sẽ trình bày
từng nhóm mã trạng thái này trong một phần riêng biệt:
Các mã phản hồi này chỉ được sử dụng trong các cuộc đàm phán giữa máy khách HTTP và
máy chủ.
Bất kỳ chuyển đổi trạng thái nào mà khách hàng yêu cầu đều đã xảy ra.
Quá trình chuyển đổi trạng thái mà khách hàng yêu cầu đã không xảy ra. Nhưng nếu khách hàng
sẵn sàng thực hiện một yêu cầu HTTP hơi khác một chút thì yêu cầu đó sẽ thực hiện những gì
Quá trình chuyển đổi trạng thái mà máy khách yêu cầu đã không xảy ra do có sự cố với yêu cầu
HTTP. Yêu cầu không đúng định dạng, không mạch lạc, tự mâu thuẫn hoặc yêu cầu mà máy chủ
Quá trình chuyển đổi trạng thái mà máy khách yêu cầu đã không xảy ra do sự cố ở phía máy chủ.
Có lẽ khách hàng không thể làm gì ngoài việc chờ sự cố được khắc phục.
Trước khi xem qua danh sách lớn các mã trạng thái, tôi chỉ muốn liệt kê bốn mã mà tôi coi là mức
tối thiểu cho API. Có một mã cho mỗi họ (ngoài 1xx mà bạn ít nhiều có thể bỏ qua): 200 (OK)
Mọi thứ đều ổn. Tài liệu trong phần thân thực thể, nếu có, là sự thể hiện của
một số tài nguyên.
Được gửi khi máy khách kích hoạt quá trình chuyển đổi trạng thái để di chuyển tài nguyên từ
URL này sang URL khác. Sau khi di chuyển, các yêu cầu tới URL cũ cũng sẽ dẫn đến mã trạng
thái 301.
Có một vấn đề ở phía khách hàng. Tài liệu trong phần thân thực thể, nếu có, là một thông báo
lỗi. Hy vọng khách hàng có thể hiểu được thông báo lỗi và sử dụng nó để khắc phục sự cố.
Có một vấn đề ở phía máy chủ. Tài liệu trong phần thân thực thể, nếu có, là một thông báo
lỗi. Thông báo lỗi có thể không có tác dụng gì nhiều vì máy khách không thể khắc phục sự cố
máy chủ.
Nếu tôi có thể thêm hai lỗi nữa thì đó sẽ là các loại lỗi máy khách khác nhau: 404 (Không tìm
thấy) và 409 (Xung đột). Khi cần cung cấp thêm chi tiết, bạn có thể sử dụng mã trạng thái khác từ
danh sách lớn hoặc cung cấp tài liệu chi tiết về vấn đề.
Và bây giờ, danh sách lớn. Trừ khi có ghi chú khác, tất cả các mã trạng thái này được xác định chính thức
trong RFC 2616.
Đây là một trong những phản hồi có thể có đối với yêu cầu xem trước HTTP (LBYL) mà tôi đã mô tả trong Chương
11. Mã trạng thái này cho biết rằng máy khách nên gửi lại yêu cầu ban đầu của nó, bao gồm cả yêu cầu (có thể
lớn hoặc nhạy cảm) đại diện đã bị bỏ qua lần đầu tiên. Khách hàng không còn phải lo lắng về việc gửi bản
trình bày rồi bị từ chối. Phản hồi có thể có khác đối với yêu cầu xem trước khi nhảy là 417 (Kỳ vọng không
thành công).
Tiêu đề yêu cầu: Để thực hiện yêu cầu LBYL, khách hàng phải đặt tiêu đề Expect thành giá trị bằng chữ “100-
continue”. Máy khách cũng phải đặt bất kỳ tiêu đề nào khác mà máy chủ sẽ cần khi xác định xem nên phản hồi
Tầm quan trọng: Rất thấp, có khả năng ở mức trung bình.
Máy khách sẽ chỉ nhận được mã phản hồi này khi yêu cầu của nó sử dụng tiêu đề Nâng cấp để thông báo cho máy
chủ rằng máy khách muốn sử dụng một số giao thức khác ngoài HTTP.
Phản hồi là 101 có nghĩa là “Được rồi, bây giờ tôi đang nói một giao thức khác.” Thông thường, máy khách HTTP
sẽ đóng kết nối TCP sau khi đọc phản hồi từ máy chủ.
Nhưng mã phản hồi là 101 có nghĩa là đã đến lúc máy khách để mở kết nối nhưng ngừng làm máy khách HTTP và bắt
Tiêu đề Nâng cấp hầu như không bao giờ được sử dụng, mặc dù nó có thể được sử dụng để chuyển đổi từ HTTP sang
HTTPS hoặc từ phiên bản 1.1 của HTTP sang phiên bản 2.0 sắp ra mắt. Nó cũng có thể được sử dụng để chuyển từ
HTTP sang một giao thức hoàn toàn khác như IRC, nhưng điều đó sẽ yêu cầu máy chủ web cũng phải là máy chủ IRC
và máy khách web cũng phải là máy khách IRC, vì máy chủ bắt đầu nói giao thức mới ngay lập tức , trên cùng
Tiêu đề yêu cầu: Máy khách đặt Nâng cấp lên danh sách các giao thức mà nó muốn sử dụng hơn HTTP.
Tiêu đề phản hồi: Nếu máy chủ muốn nâng cấp, nó sẽ gửi lại tiêu đề Nâng cấp cho biết nó đang chuyển sang giao
thức nào và sau đó là một dòng trống. Thay vì đóng giao thức TCP
nối, máy chủ bắt đầu nói giao thức mới và tiếp tục nói giao thức mới cho đến khi kết nối được đóng
lại.
Mã trạng thái 2xx cho biết rằng bất kỳ chuyển đổi trạng thái nào mà khách hàng yêu cầu đều đã xảy
ra.
200 (Được)
Trong hầu hết các trường hợp, đây là mã mà khách hàng hy vọng nhìn thấy. Nó chỉ ra rằng quá trình
chuyển đổi trạng thái đã hoàn tất và không còn mã cụ thể nào trong chuỗi 2xx là phù hợp.
Phần thân thực thể: Đối với yêu cầu GET, đại diện cho tài nguyên là mục tiêu của GET. (Điều này sẽ
gây ra thay đổi trạng thái ứng dụng.) Đối với các yêu cầu khác, mô tả về thay đổi trạng thái tài
nguyên: biểu thị trạng thái hiện tại của tài nguyên đã chọn hoặc mô tả về chính quá trình chuyển
Máy chủ gửi mã trạng thái này khi nó tạo tài nguyên mới theo yêu cầu của máy khách.
Tiêu đề phản hồi: Tiêu đề Vị trí phải chứa URL chuẩn cho địa chỉ mới
nguồn.
Entity-body: Nên mô tả và liên kết tới tài nguyên mới được tạo. Việc thể hiện tài nguyên đó có thể
được chấp nhận nếu bạn sử dụng tiêu đề Vị trí để cho khách hàng biết nơi tài nguyên thực sự tồn tại.
Yêu cầu của khách hàng không thể hoặc sẽ không được xử lý trong thời gian thực. Nó sẽ được xử lý
sau. Yêu cầu có vẻ hợp lệ nhưng có thể lại gặp sự cố khi máy chủ thực sự truy cập được yêu cầu đó.
Đây là phản hồi thích hợp khi một yêu cầu kích hoạt một hành động không đồng bộ, một hành động
trong thế giới thực hoặc quá trình chuyển đổi trạng thái mất nhiều thời gian đến mức không có ích
Tiêu đề yêu cầu: Tiêu đề Ưu tiên (xem Phụ lục B) cho phép máy khách báo cho máy chủ biết họ sẵn
sàng chờ bao lâu để nhận được phản hồi thực sự thay vì 202.
Tiêu đề phản hồi: Yêu cầu đang chờ xử lý phải được hiển thị dưới dạng một loại tài nguyên nào đó để
khách hàng có thể kiểm tra nó sau. Tiêu đề Vị trí có thể chứa URL tới đây
nguồn.
Thực thể-nội dung: Nếu sau này khách hàng không có cách nào kiểm tra yêu cầu, ít nhất hãy đưa ra ước
tính về thời điểm yêu cầu sẽ được xử lý. Ở đây, tài liệu chi tiết về vấn đề có thể phù hợp, mặc dù về
Retry-After: Tiêu đề Retry-After có thể được sử dụng để cho biết ước tính của máy chủ về thời điểm phản
hồi đầy đủ sẽ sẵn sàng. Tiêu đề này được thiết kế để sử dụng với mã phản hồi 5xx và 3xx nhưng cũng có
Mã trạng thái này giống như 200 (OK), nhưng máy chủ muốn máy khách biết rằng một số tiêu đề phản hồi
không đến từ máy chủ. Chúng có thể được phản ánh từ yêu cầu trước đó của khách hàng hoặc được lấy từ
Tiêu đề phản hồi: Máy khách nên biết rằng một số tiêu đề có thể không chính xác và những tiêu đề khác
có thể được chuyển đi mà máy chủ không biết ý nghĩa của chúng.
Mã trạng thái này thường được gửi đi để đáp lại yêu cầu không an toàn, chẳng hạn như yêu cầu PUT. Điều
đó có nghĩa là máy chủ đã thực hiện chuyển đổi trạng thái nhưng từ chối gửi lại bất kỳ đại diện hoặc
Máy chủ cũng có thể gửi 204 để đáp lại yêu cầu GET. Điều này có nghĩa là tài nguyên được yêu cầu tồn
tại nhưng có phần trình bày trống. So sánh 304 (Không sửa đổi).
204 thường là các ứng dụng JavaScript trong trình duyệt. Nó cho phép máy chủ thông báo cho máy khách biết rằng đầu vào
của nó đã được chấp nhận, nhưng máy khách không được thay đổi bất kỳ thành phần giao diện người dùng nào.
Điều này giống như 204 (Không có nội dung), nhưng nó ngụ ý rằng khách hàng nên đặt lại chế độ xem hoặc
cấu trúc dữ liệu vốn là nguồn của dữ liệu. Nếu bạn gửi biểu mẫu HTML trong trình duyệt web của mình và
phản hồi là 204 (“Không có nội dung”) thì dữ liệu của bạn vẫn ở dạng đó và bạn có thể thay đổi nó. Nếu
bạn nhận được 205, các trường của biểu mẫu sẽ đặt lại về giá trị ban đầu. Trong mục nhập dữ liệu
thuật ngữ: 204 phù hợp để thực hiện một loạt chỉnh sửa cho một bản ghi; 205 phù hợp để nhập một loạt
bản ghi liên tiếp.
Tầm quan trọng: Rất cao đối với các API hỗ trợ GET một phần, nếu không thì thấp.
Giá trị này giống như 200 (OK), nhưng nó chỉ định phản hồi cho yêu cầu GET một phần: tức là yêu cầu sử
dụng tiêu đề yêu cầu Phạm vi nội dung . Một máy khách thường thực hiện một yêu cầu GET một phần để
tiếp tục quá trình tải xuống bị gián đoạn của một biểu diễn nhị phân lớn. Tôi trình bày một phần GET
Tiêu đề yêu cầu: Máy khách gửi một giá trị cho tiêu đề Phạm vi nội dung .
Tiêu đề phản hồi: Tiêu đề ngày là bắt buộc. Các tiêu đề ETag và Content-Location phải được đặt thành
cùng các giá trị đã được gửi cùng với toàn bộ bản trình bày.
Nếu phần nội dung thực thể là một phạm vi byte đơn từ biểu diễn thì toàn bộ phản hồi phải có tiêu đề
Phạm vi nội dung giải thích byte nào của biểu diễn đang được phân phối. Nếu phần nội dung là một thực
thể nhiều phần (nghĩa là, nhiều phạm vi byte của biểu diễn đang được phân phát), thì loại phương tiện
tổng thể là nhiều phần/dải byte và mỗi phần phải có tiêu đề Phạm vi nội dung riêng của nó .
Phần thân thực thể: Sẽ không chứa biểu diễn đầy đủ, chỉ chứa một hoặc nhiều chuỗi byte từ biểu diễn.
Quá trình chuyển đổi trạng thái mà khách hàng yêu cầu đã không xảy ra. Nhưng nếu khách hàng sẵn sàng
thực hiện một yêu cầu HTTP hơi khác một chút thì yêu cầu đó sẽ thực hiện những gì khách hàng yêu cầu.
Nói chung, khách hàng cần lặp lại yêu cầu của mình với một tài nguyên khác.
Đây là bộ mã phản hồi phức tạp nhất, vì 301 (Đã di chuyển vĩnh viễn), 302 (Đã tìm thấy), 303 (Xem phần
khác) và 307 (Chuyển hướng tạm thời), đều rất giống nhau. Nhiều ứng dụng sử dụng các mã trạng thái này
một cách bừa bãi như một cách ném máy khách như một quả bóng qua máy pinball hypermedia mà không quan
tâm đến ý nghĩa của điều này về mặt ngữ nghĩa ứng dụng. Mục tiêu chính của tôi trong phần này là làm
Máy chủ có thể gửi mã trạng thái này khi nó có nhiều cách thể hiện một tài nguyên được yêu cầu và nó
không biết khách hàng muốn cách thể hiện nào. Hoặc là khách hàng
không sử dụng các tiêu đề Accept-* để chỉ định một biểu diễn hoặc nó yêu cầu một biểu diễn không
tồn tại.
Trong tình huống này, máy chủ chỉ có thể chọn biểu diễn ưa thích và gửi nó cùng với mã trạng thái
200 (OK) . Nhưng thay vào đó, nó có thể quyết định gửi 300 cùng với danh sách các URI có thể có
Tiêu đề phản hồi: Nếu máy chủ có biểu diễn ưu tiên, nó có thể đặt URI vào biểu diễn đó trong Vị
trí. Giống như hầu hết các mã trạng thái 3xx khác, khách hàng có thể tự động theo dõi URI trong
Vị trí.
Entity-body: Danh sách các liên kết hypermedia, cùng với ngữ nghĩa ứng dụng cần thiết để cho phép
người dùng lựa chọn giữa chúng.
Máy chủ biết khách hàng đang cố truy cập tài nguyên nào, nhưng khách hàng không quan tâm đến URL
mà nó sử dụng để yêu cầu tài nguyên. Nó muốn khách hàng ghi lại URL mới và sử dụng nó trong các
Bạn có thể sử dụng mã trạng thái này để giữ cho các URL cũ không bị hỏng khi API của bạn thay đổi
cấu trúc URL.
Tiêu đề phản hồi: Máy chủ phải đặt URL chuẩn vào Vị trí.
Entity-body: Máy chủ sẽ gửi tài liệu hypermedia liên kết đến lo- mới
cation.
Tầm quan trọng: Rất quan trọng cần biết, đặc biệt là khi viết thư cho khách hàng. Tôi không khuyên
Mã trạng thái này là nguồn gốc cuối cùng của hầu hết các nhầm lẫn liên quan đến chuyển hướng. Nó
được cho là được xử lý giống như 307 (Chuyển hướng tạm thời). Trên thực tế, trong HTTP 1.0, tên
của nó là Đã di chuyển tạm thời. Thật không may, trong đời thực, hầu hết khách hàng đều xử lý 302
giống như 303 (Xem phần khác). Sự khác biệt xoay quanh những gì khách hàng phải làm khi nhận được
302 để phản hồi yêu cầu PUT, POST hoặc DELETE. Xem các mục dành cho 307 và 308 (Chuyển hướng vĩnh
Để giải quyết sự mơ hồ này, trong HTTP 1.1, mã phản hồi này đã được đổi tên thành Đã tìm thấy và
mã phản hồi 307 đã được tạo. Mã phản hồi này vẫn được sử dụng rộng rãi nhưng không rõ ràng và tôi
khuyên máy chủ của bạn nên gửi 303, 307 và 308 thay thế.
Tiêu đề phản hồi: Tiêu đề Vị trí chứa URL mà khách hàng sẽ gửi lại yêu cầu.
Nội dung thực thể: Phải chứa liên kết hypermedia đến URL mới, như với 301.
Yêu cầu đã được xử lý nhưng thay vì máy chủ gửi tài liệu phản hồi, nó lại gửi cho khách hàng URL
của tài liệu phản hồi. Đây có thể là URL của thông báo trạng thái tĩnh hoặc của một số tài nguyên
thú vị hơn. Trong trường hợp sau, 303 là cách để máy chủ gửi bản trình bày của tài nguyên mà
không buộc máy khách phải tải xuống tất cả dữ liệu đó. Khách hàng dự kiến sẽ thực hiện yêu cầu
GET tới URL được đề cập trong Vị trí, nhưng không nhất thiết phải làm như vậy.
Mã trạng thái 303 là một cách hay để chuẩn hóa tài nguyên của bạn. Bạn có thể cung cấp chúng
thông qua nhiều URL, nhưng chỉ có một URL “thực” cho mỗi đại diện. Tất cả các URL khác đều sử
dụng 303 để trỏ đến URL chuẩn cho phần trình bày đó. Ví dụ: 303 có thể chuyển hướng yêu cầu
Tiêu đề phản hồi: Tiêu đề Vị trí chứa URL của phần trình bày.
Nội dung thực thể: Phải chứa liên kết hypermedia đến URL mới, như với 301.
Mã trạng thái này tương tự như 204 (Không có nội dung) ở chỗ phần nội dung phản hồi phải trống.
Nhưng 204 được sử dụng khi không có dữ liệu nội dung để gửi và 304 được sử dụng khi có dữ liệu
nhưng khách hàng đã có dữ liệu đó. Không có ích gì khi gửi lại lần nữa.
Mã trạng thái này được sử dụng cùng với các yêu cầu HTTP có điều kiện. Nếu khách hàng gửi tiêu
đề If-Modified-Since có ngày Chủ nhật và phần trình bày không thay đổi kể từ Chủ nhật thì 304 là
phù hợp. Giá trị 200 (OK) cũng phù hợp, nhưng việc gửi lại bản trình bày sẽ lãng phí băng thông
Tiêu đề phản hồi: Tiêu đề ngày là bắt buộc. Tiêu đề ETag và Content-Location phải được đặt thành
cùng giá trị sẽ được gửi nếu mã phản hồi là 200 (OK).
Các tiêu đề bộ nhớ đệm hết hạn, Kiểm soát bộ đệm và Vary là bắt buộc nếu chúng đã thay đổi so với
Có những quy tắc bộ nhớ đệm phức tạp về vấn đề này mà tôi sẽ không đề cập ở đây, nhưng máy chủ có thể gửi các
tiêu đề đã cập nhật mà không cần gửi nội dung mới. Điều này hữu ích khi siêu dữ liệu của một biểu diễn đã thay
Mã trạng thái này được sử dụng để thông báo cho khách hàng rằng họ nên lặp lại yêu cầu của mình nhưng phải thông
qua proxy HTTP thay vì truy cập trực tiếp vào máy chủ. Mã này hiếm khi được sử dụng vì rất hiếm khi máy chủ quan
Mã này sẽ được sử dụng thường xuyên hơn nếu có các trang nhân bản dựa trên proxy. Ngày nay, một trang web nhân
bản cho http://www.example.com/ cung cấp cùng một nội dung nhưng ở một URL khác, chẳng hạn như http://
www.example.com.mysite.com/. Trang web ban đầu có thể sử dụng mã trạng thái 307 (Chuyển hướng tạm thời) để gửi
khách hàng đến một trang web nhân bản thích hợp.
Nếu có các trang web nhân bản dựa trên proxy thì bạn sẽ truy cập nhân bản có cùng URL với trang gốc (http://
www.example.com/), nhưng đặt http://proxy.mysite.com/ làm proxy của bạn . Ở đây, example.com ban đầu có thể sử
dụng mã trạng thái 305 để định tuyến máy khách đến proxy nhân bản gần với chúng về mặt địa lý.
Các trình duyệt web thường không xử lý mã trạng thái này một cách chính xác: một lý do khác khiến nó không phổ
biến.
Mã trạng thái 306 chưa bao giờ được chuyển thành RFC. Nó đã được mô tả trong Internet-Draft
“draft-cohen-http-305-306-responses” dưới dạng Switch Proxy, mã trạng thái được gửi bởi máy chủ proxy để yêu cầu
khách hàng bắt đầu sử dụng một proxy khác. Bản nháp Internet đó đã hết hạn vào năm 1996, vì vậy đừng lo lắng về
điều đó.
Yêu cầu chưa được xử lý vì tài nguyên được yêu cầu không có ở nhà: nó nằm ở một số URL khác. Khách hàng nên gửi
Đối với các yêu cầu GET, trong đó điều duy nhất được yêu cầu là máy chủ gửi một thông báo, mã trạng thái này
giống với 303 (Xem phần Khác). Một trường hợp điển hình trong đó 307 là phản hồi tốt cho GET là khi máy chủ muốn
gửi khách hàng đến một trang web nhân bản. Nhưng
đối với các yêu cầu POST, PUT và DELETE, trong đó máy chủ dự kiến sẽ thực hiện một số hành động để đáp
ứng yêu cầu, mã trạng thái này khác biệt đáng kể so với 303.
303 phản hồi POST, PUT hoặc DELETE có nghĩa là thao tác đã thành công nhưng nội dung thực thể phản hồi
không được gửi cùng với yêu cầu này. Nếu máy khách muốn nội dung thực thể phản hồi, nó cần thực hiện
Lỗi 307 phản hồi POST, PUT hoặc DELETE có nghĩa là máy chủ thậm chí chưa thử thực hiện thao tác. Khách
hàng cần gửi lại toàn bộ yêu cầu tới URL trong tiêu đề Vị trí .
Một sự tương tự có thể giúp ích. Bạn đến hiệu thuốc với đơn thuốc cần mua. 303 là dược sĩ nói “Chúng
tôi đã mua thuốc theo toa của bạn. Hãy đến cửa sổ tiếp theo để lấy thuốc của bạn ”. Số 307 là dược sĩ
nói “Chúng tôi hết thuốc đó rồi. Tới hiệu thuốc bên cạnh.”
Tiêu đề phản hồi: Tiêu đề Vị trí chứa URL mà khách hàng sẽ gửi lại yêu cầu.
Nội dung thực thể: Phải chứa liên kết hypermedia đến URL mới, như với 301.
308 để đáp lại yêu cầu GET giống như 301 (Đã di chuyển vĩnh viễn). Nhưng 308 để phản hồi yêu cầu không
an toàn hoạt động giống như 307 (Chuyển hướng tạm thời): khách hàng phải gửi lại yêu cầu tới URL được
cung cấp trong tiêu đề Vị trí . Sự khác biệt là khách hàng cũng nên sử dụng URL được cung cấp trong
tiêu đề Vị trí cho bất kỳ yêu cầu nào mà họ đang nghĩ đến việc thực hiện trong tương lai .
Để tiếp tục so sánh hiệu thuốc với thảo luận của tôi về 307 (Chuyển hướng tạm thời), mã phản hồi 308 là
một hiệu thuốc đã ngừng hoạt động. Trở lại sau sẽ không giúp ích gì. Bạn sẽ phải mang đơn thuốc và mọi
công việc kinh doanh trong tương lai đến hiệu thuốc bên cạnh.
Mã trạng thái này được xác định trong phần mở rộng của HTTP vẫn ở dạng Bản nháp Internet.
Ngay cả sau khi nó trở thành RFC, có thể sẽ an toàn hơn khi sử dụng 307 ngay cả đối với các chuyển hướng
vĩnh viễn. Khách hàng có thể không hiểu mã phản hồi 308 nghĩa là gì.
Các mã trạng thái này cho biết có điều gì đó không ổn ở phía máy khách. Có vấn đề với việc xác thực,
với định dạng trình bày, với thời gian của yêu cầu hoặc với chính ứng dụng khách HTTP. Khách hàng cần
Chi tiết vấn đề (xem Chương 10) hữu ích nhất cho chuỗi mã 4xx. Đối với hầu hết các mã lỗi này, tôi nói rằng phần
nội dung thực thể có thể chứa một “tài liệu”. Trừ khi bạn đang sử dụng định dạng trình bày có cơ chế báo cáo lỗi
tích hợp, tôi khuyên bạn nên biến tài liệu đó thành một chi tiết vấn đề.
Đây là trạng thái lỗi chung phía máy khách, được sử dụng khi không có mã lỗi 4xx nào khác phù hợp. Nó thường được
sử dụng khi khách hàng gửi một biểu diễn cùng với yêu cầu PUT hoặc POST và biểu diễn đó có định dạng phù hợp,
Phần thân thực thể: Có thể chứa tài liệu giải thích quan điểm của máy chủ về vấn đề phía máy khách.
Máy khách đã gửi yêu cầu đến một tài nguyên được bảo vệ mà không cung cấp thông tin xác thực phù hợp. Nó có thể
đã cung cấp thông tin xác thực sai hoặc không có thông tin nào cả. Thông tin đăng nhập có thể là tên người dùng
và mật khẩu, khóa API hoặc mã thông báo xác thực —bất kể API được đề cập đang mong đợi điều gì. Thông thường,
khách hàng sẽ yêu cầu một URL và chấp nhận 401 chỉ để biết loại thông tin xác thực nào cần gửi và ở định dạng
nào. Trên thực tế, chế độ xác thực HTTP Digest phụ thuộc vào hành vi này.
Nếu máy chủ không muốn thừa nhận sự tồn tại của tài nguyên đối với người dùng trái phép, nó có thể nói dối và gửi
404 (Không tìm thấy) thay vì 401. Nhược điểm của việc này là khách hàng cần biết trước loại tài nguyên nào. xác
thực mà máy chủ mong đợi đối với tài nguyên đó. Các giao thức như HTTP Digest sẽ không hoạt động.
Tiêu đề phản hồi: Tiêu đề WWW-Authenticate mô tả loại xác thực mà máy chủ sẽ chấp nhận.
Thực thể-nội dung: Tài liệu mô tả lỗi; tại sao thông tin xác thực (nếu có được cung cấp) bị từ chối và thông tin
xác thực nào sẽ được chấp nhận. Nếu người dùng cuối là con người có thể nhận được thông tin xác thực bằng cách
đăng ký trên một trang web hoặc tạo tài nguyên “tài khoản người dùng”, thì liên kết hypermedia đến tài nguyên
Ngoài tên của nó, mã trạng thái này không được xác định trong tiêu chuẩn HTTP: nó “được dành riêng để sử dụng
trong tương lai”. Điều này là do không có hệ thống thanh toán vi mô cho HTTP. Điều đó nói lên rằng, nếu
từng có hệ thống thanh toán vi mô cho HTTP, API là một trong những nơi đầu tiên mà hệ thống sẽ bắt đầu hiển
thị. Nếu bạn muốn tính phí người dùng theo yêu cầu HTTP và mối quan hệ của bạn với họ khiến điều đó trở nên
Nhưng đã có rất nhiều API tính phí theo yêu cầu và tôi không biết API nào sử dụng mã trạng thái này. Có lẽ
403 (Cấm)
Tầm quan trọng: Trung bình.
Yêu cầu của khách hàng được hình thành chính xác, nhưng máy chủ không muốn thực hiện nó.
Đây không chỉ đơn thuần là trường hợp không đủ thông tin xác thực: đó sẽ là 401 (Không được phép).
Đây giống như một tài nguyên chỉ có thể truy cập được vào những thời điểm nhất định hoặc từ một số địa chỉ
IP nhất định.
Phản hồi 403 ngụ ý rằng khách hàng gửi yêu cầu đến một tài nguyên thực sự tồn tại.
Giống như 401 (Không được phép), nếu máy chủ không muốn cung cấp thông tin này, nó có thể nói dối và gửi
Nếu yêu cầu của khách hàng được định dạng đúng, tại sao mã trạng thái này lại nằm trong chuỗi 4xx (lỗi phía
máy khách) thay vì chuỗi 5xx (lỗi phía máy chủ)? Bởi vì máy chủ đưa ra quyết định dựa trên một số khía cạnh
của yêu cầu ngoài hình thức của nó: giả sử thời gian trong ngày yêu cầu được thực hiện.
Thực thể-nội dung: Một tài liệu tùy chọn giải thích lý do tại sao yêu cầu bị từ chối.
Có lẽ là mã trạng thái HTTP nổi tiếng nhất. 404 cho biết máy chủ không thể ánh xạ URL của máy khách tới tài
nguyên. So sánh 410 (Đã qua), hữu ích hơn một chút.
Hãy nhớ rằng 404 có thể là lời nói dối để che đậy 403 hoặc 401. Có thể tài nguyên đó tồn tại nhưng máy chủ
không muốn cho khách hàng biết về điều đó.
Phần thân thực thể: Tài liệu tùy chọn giải thích lỗi. Tài liệu có thể chứa điều khiển siêu phương tiện để
tạo tài nguyên tại vị trí này (có thể sử dụng HTTP PUT).
Máy khách đã cố gắng sử dụng phương thức HTTP mà tài nguyên này không hỗ trợ. Chẳng hạn, tài nguyên chỉ đọc
có thể chỉ hỗ trợ GET và HEAD. Tài nguyên bộ sưu tập (như được xác định bởi mẫu bộ sưu tập) thường cho phép
Tiêu đề phản hồi: Tiêu đề Cho phép liệt kê các phương thức HTTP mà tài nguyên này hỗ trợ. Sau đây
Máy chủ có thể gửi mã phản hồi này khi máy khách đặt ra quá nhiều hạn chế đối với những gì nó coi
là đại diện có thể chấp nhận được (có thể sử dụng tiêu đề yêu cầu Accept-* ) mà máy chủ không thể
gửi bất kỳ đại diện nào cả. Thay vào đó, máy chủ có thể chọn bỏ qua sự kén chọn của khách hàng và
chỉ cần gửi đại diện ưa thích của mình cùng với mã phản hồi là 200 (OK). Đây thường là những gì
Phần thân thực thể: Một tài liệu siêu phương tiện liên kết đến các biểu diễn có thể chấp nhận được, ở
định dạng tương tự như định dạng được mô tả trong 300 (Nhiều lựa chọn).
Bạn sẽ chỉ thấy mã trạng thái này từ proxy HTTP. Nó giống như 401 (Không được phép), ngoại trừ vấn
đề không phải là bạn không thể sử dụng API mà không có thông tin xác thực; đó là bạn không thể sử
dụng proxy mà không có thông tin xác thực. Giống như 401, vấn đề có thể là do khách hàng không cung
cấp thông tin xác thực hoặc thông tin xác thực được cung cấp không hợp lệ hoặc không đầy đủ.
Tiêu đề yêu cầu: Để gửi thông tin xác thực đến proxy, máy khách sử dụng tiêu đề Ủy quyền proxy
thay vì tiêu đề Ủy quyền . Định dạng giống hệt với
đó là sự ủy quyền.
Tiêu đề phản hồi: Thay vì tiêu đề Xác thực , proxy sẽ điền vào tiêu đề Proxy-Authenticate thông
Lưu ý rằng cả proxy và API đều có thể yêu cầu thông tin xác thực, do đó, khách hàng có thể xóa 407
Phần thân thực thể: Một tài liệu mô tả lỗi, giống như tài liệu tôi đã mô tả cho mã trạng thái
401.
Nếu máy khách HTTP mở kết nối đến máy chủ nhưng không bao giờ gửi yêu cầu (hoặc không bao giờ gửi
dòng trống báo hiệu kết thúc yêu cầu), thì cuối cùng máy chủ sẽ gửi mã phản hồi 408 và đóng kết nối.
Máy khách đã cố gắng tạo trạng thái tài nguyên không thể hoặc không nhất quán trên máy chủ. Thế nào là
“không thể” hoặc “không nhất quán” tùy thuộc vào ngữ nghĩa ứng dụng của API. API dựa trên bộ sưu tập có
thể cho phép khách hàng XÓA một bộ sưu tập trống, nhưng gửi 409 khi khách hàng cố gắng XÓA một bộ sưu tập
vẫn chứa các thành viên.
Tiêu đề phản hồi: Nếu xung đột xảy ra do sự tồn tại của một số tài nguyên khác (ví dụ: khách hàng cố gắng
tạo một tài nguyên đặc biệt đã tồn tại), tiêu đề Vị trí sẽ liên kết đến URL của tài nguyên đó: nghĩa là
nguồn của tài nguyên đó. xung đột.
Thực thể-nội dung: Nên chứa tài liệu mô tả các xung đột để khách hàng có thể giải quyết chúng nếu có thể.
Mã phản hồi này giống như 404 (Không tìm thấy), nhưng nó cung cấp thêm một chút thông tin.
Nó được sử dụng khi máy chủ biết rằng URL được yêu cầu từng tham chiếu đến một tài nguyên nhưng không còn
nữa. Máy chủ không biết bất kỳ URL mới nào cho tài nguyên; nếu đúng như vậy, nó sẽ gửi 301 (Chuyển hướng
vĩnh viễn).
Giống như chuyển hướng vĩnh viễn, mã phản hồi 410 có hàm ý rằng khách hàng nên xóa URL hiện tại khỏi từ
điển của nó và ngừng đưa ra yêu cầu đối với URL đó.
Không giống như chuyển hướng vĩnh viễn, 410 không cung cấp sự thay thế cho URL xấu: nó vừa biến mất. RFC
2616 đề xuất sử dụng mã phản hồi 410 “đối với các dịch vụ khuyến mại, có thời gian giới hạn và đối với
các tài nguyên thuộc về các cá nhân không còn làm việc tại trang web của máy chủ”.
Bạn có thể muốn gửi mã phản hồi này để đáp lại yêu cầu XÓA thành công, nhưng điều đó hơi dễ thương quá.
Khách hàng sẽ không biết liệu nó đã xóa tài nguyên hay nó đã biến mất trước khi đưa ra yêu cầu của họ.
Phản hồi chính xác cho yêu cầu XÓA thành công là 200 (OK).
Yêu cầu HTTP bao gồm phần trình bày phải đặt tiêu đề yêu cầu Độ dài nội dung thành độ dài (tính bằng
byte) của nội dung thực thể. Đôi khi điều này gây bất tiện cho khách hàng: ví dụ: khi bản trình bày đang
được truyền trực tuyến từ một số nguồn khác. Vì vậy, HTTP không yêu cầu khách hàng gửi tiêu đề Độ dài nội
dung với mỗi yêu cầu. Tuy nhiên, máy chủ HTTP có quyền yêu cầu nó cho bất kỳ yêu cầu cụ thể nào.
Máy chủ được phép làm gián đoạn mọi yêu cầu bắt đầu gửi đại diện
mà không cung cấp Độ dài nội dung và yêu cầu khách hàng gửi lại yêu cầu với tiêu đề Độ dài nội dung . Đây
Nếu máy khách nói dối về độ dài hoặc gửi đại diện quá lớn, máy chủ có thể làm gián đoạn nó và đóng kết
nối, nhưng trong trường hợp đó, mã phản hồi là 413 (Thực thể yêu cầu quá lớn).
Máy khách đã chỉ định một hoặc nhiều điều kiện tiên quyết trong tiêu đề yêu cầu của mình, yêu cầu máy chủ
chỉ thực hiện yêu cầu của mình một cách hiệu quả nếu đáp ứng một số điều kiện nhất định. Trên thực tế,
những điều kiện đó không được đáp ứng nên thay vì thực hiện yêu cầu, máy chủ sẽ gửi mã trạng thái này.
Điều kiện tiên quyết phổ biến là If-Unmodified-Since. (Tôi đã đề cập đến vấn đề này trong Chương 11.) Máy
khách có thể ĐẶT yêu cầu sửa đổi tài nguyên, nhưng yêu cầu các thay đổi đó chỉ có hiệu lực nếu không có
ai khác sửa đổi tài nguyên kể từ lần cuối máy khách tìm nạp nó. Nếu không có điều kiện tiên quyết, khách
hàng có thể ghi đè lên những thay đổi của người khác mà không nhận ra hoặc có thể gây ra lỗi 409 (Xung
đột).
Tiêu đề yêu cầu: Máy khách có thể nhận được mã phản hồi này bằng cách sử dụng bất kỳ tiêu đề If-Match, If-
If-None-Match hơi đặc biệt một chút. Nếu máy khách chỉ định If-None-Match khi thực hiện yêu cầu GET hoặc
HEAD và điều kiện tiên quyết không thành công thì mã phản hồi không phải là 412 mà là 304 (Không được sửa
đổi). Đây là cơ sở của HTTP GET có điều kiện (cũng được đề cập trong Chương 11). Nếu một yêu cầu PUT,
POST hoặc DELETE sử dụng If-None-Match và điều kiện trước không thành công thì mã phản hồi là 412. Mã
phản hồi cũng là 412 khi điều kiện tiên quyết sử dụng If-Match hoặc If-Unmodified-Since tiêu đề, bất kể
Điều này tương tự như 411 (Yêu cầu độ dài) ở chỗ máy chủ có thể làm gián đoạn yêu cầu của khách hàng bằng
mã trạng thái này và đóng kết nối mà không cần đợi yêu cầu hoàn tất. Mã trạng thái 411 dành cho các yêu
cầu không chỉ định độ dài biểu diễn của chúng. Mã trạng thái này dành cho các yêu cầu gửi bản trình bày
Yêu cầu xem trước khi nhảy (xem Chương 11) là cách tốt nhất để khách hàng tránh bị gián đoạn vì lỗi này.
Nếu yêu cầu LBYL nhận được mã phản hồi là 100 (Tiếp tục), khách hàng có thể tiếp tục và gửi bản trình bày
đầy đủ.
Tiêu đề phản hồi: Sự cố có thể là tạm thời và ở phía máy chủ (thiếu tài nguyên) chứ không phải ở phía máy
khách (sự thể hiện quá lớn). Nếu vậy, máy chủ có thể đặt tiêu đề Thử lại sau thành một ngày hoặc một số
giây và máy khách có thể thử lại yêu cầu của mình sau.
Tiêu chuẩn HTTP không áp đặt giới hạn chính thức nào về độ dài của URL (và theo tôi, không nên có bất kỳ
giới hạn nào). Tuy nhiên, hầu hết các máy chủ web hiện tại đều áp đặt giới hạn trên cho độ dài của URL và
API có thể làm điều tương tự. Nguyên nhân phổ biến nhất là do máy khách đặt trạng thái tài nguyên vào URL
trong khi lẽ ra nó phải nằm trong phần nội dung thực thể. Cấu trúc dữ liệu lồng nhau sâu cũng có thể
khiến URL rất dài. Nếu đây là vấn đề đối với bạn, hãy cung cấp cho tài nguyên của bạn các URL mờ được tạo
bằng số ngẫu nhiên, thay vì để các URL dài hơn, chẳng hạn như một kilobyte.
Nếu máy khách kết nối với máy chủ và bắt đầu gửi một URL dài vô hạn, ngay cả máy chủ không áp đặt độ dài
URL tối đa được xác định trước cuối cùng cũng có thể làm gián đoạn yêu cầu bằng phản hồi 414, để giải
phóng kết nối TCP. Máy chủ cũng có thể đơn giản ngắt kết nối.
Máy chủ gửi mã trạng thái này khi máy khách gửi một biểu diễn bằng loại phương tiện mà nó không hiểu. Máy
chủ có thể đã mong đợi application/vnd.collec tion+json và máy khách đã gửi application/json.
Nếu khách hàng gửi tài liệu có đúng loại phương tiện nhưng sai định dạng (chẳng hạn như tài liệu XML được
viết bằng từ vựng sai hoặc tài liệu Collection+JSON sử dụng cấu hình ALPS sai), thì phản hồi tốt hơn là
Máy chủ gửi mã trạng thái này khi máy khách yêu cầu một loạt phạm vi byte từ một biểu diễn, nhưng biểu
để áp dụng. Nói cách khác, nếu bạn yêu cầu byte 100 của biểu diễn 99 byte, bạn sẽ nhận được mã trạng thái
này.
Tiêu đề yêu cầu: Mã trạng thái này sẽ chỉ được gửi khi yêu cầu ban đầu bao gồm trường yêu cầu tiêu đề
Phạm vi . Nó sẽ không được gửi nếu yêu cầu ban đầu bao gồm trường yêu cầu tiêu đề If-Range ;
Tiêu đề phản hồi: Máy chủ sẽ gửi trường Phạm vi nội dung cho khách hàng biết kích thước thực tế của biểu
diễn.
Mã phản hồi này là mặt trái của 100 (Tiếp tục). Nếu bạn đưa ra yêu cầu xem trước khi nhảy để xem liệu
máy chủ có chấp nhận thông tin đại diện của bạn hay không và máy chủ quyết định điều đó thì bạn sẽ nhận
được mã phản hồi 100 và bạn có thể tiếp tục. Nếu máy chủ quyết định sẽ không chấp nhận thông tin đại diện
của bạn, bạn sẽ nhận được mã phản hồi 417 và bạn không cần phải gửi thông tin đại diện của mình.
Trong Chương 11, tôi khuyên rằng việc triển khai API yêu cầu khách hàng thực hiện các yêu cầu PUT và
PATCH có điều kiện, như một cách để tránh sự cố mất cập nhật.
Các máy chủ web thực thi quy tắc đó bằng mã trạng thái này, cho biết yêu cầu của khách hàng đang bị từ
Phần thân thực thể: Nên chứa tài liệu giải thích các tiêu đề có điều kiện nào (có thể là If-Match hoặc If-
Mã trạng thái này thực thi chính sách giới hạn tốc độ của máy chủ. Gần đây khách hàng đã gửi quá nhiều
Máy chủ được phép đơn giản bỏ qua các yêu cầu vi phạm chính sách giới hạn tốc độ, thay vì phản hồi từng
Tiêu đề phản hồi: Tiêu đề Thử lại sau sẽ đưa ra gợi ý về thời điểm máy chủ sẽ chấp nhận lại yêu cầu từ
Thực thể-nội dung: Nên chứa tài liệu giải thích chính sách giới hạn tỷ lệ.
Điều này giống như 413 (Thực thể yêu cầu quá lớn) hoặc 414 (URL yêu cầu quá dài), nhưng vấn đề ở đây
Việc máy chủ đặt giới hạn được xác định trước về kích thước của tiêu đề yêu cầu là hợp pháp nhưng tôi
không nghĩ đó là một ý tưởng hay. Đặc biệt, tiêu đề Liên kết có thể khá lớn một cách hợp pháp . Nếu
máy khách kết nối với máy chủ và bắt đầu gửi yêu cầu với tiêu đề dài vô hạn, máy chủ có thể làm gián
đoạn yêu cầu bằng phản hồi 431. (Máy chủ cũng có thể ngắt kết nối.)
Nội dung thực thể: Nếu có một tiêu đề cụ thể quá lớn (ngược lại với các tiêu đề chung là quá lớn), nội
dung thực thể nên đề cập đến tiêu đề nào có vấn đề.
Yêu cầu của khách hàng được hình thành đúng cách, nhưng về mặt pháp lý, máy chủ buộc phải từ chối yêu
cầu đó. Thông thường điều này là do máy chủ bị cấm cung cấp thông tin đại diện thông qua một số hình
thức kiểm duyệt. Máy chủ cũng có thể sử dụng mã trạng thái này khi từ chối thực hiện chuyển đổi trạng
thái tài nguyên.
Đây được coi là lỗi phía máy khách mặc dù yêu cầu được định dạng đúng và yêu cầu pháp lý tồn tại ở
phía máy chủ. Rốt cuộc, sự đại diện đó đã bị kiểm duyệt là có lý do. Chắc hẳn có điều gì đó không ổn
Chuỗi mã trạng thái 5xx dùng để biểu thị các sự cố ở phía máy chủ. Các mã này thường có nghĩa là máy
chủ không ở trạng thái thực hiện yêu cầu của khách hàng hoặc thậm chí xem liệu yêu cầu đó có đúng hay
không và khách hàng nên thử lại yêu cầu của mình sau. Đôi khi máy chủ có thể ước tính thời điểm máy
khách nên thử lại yêu cầu của mình và đưa thông tin đó vào tiêu đề phản hồi Thử lại sau .
Có ít mã trạng thái 5xx hơn mã trạng thái 4xx, không phải vì ít lỗi xảy ra trên máy chủ hơn mà vì không
có nhiều ý nghĩa cụ thể. Máy khách không thể làm gì để khắc phục sự cố trên máy chủ.
Tất cả các phản hồi sử dụng các mã trạng thái này đều có thể bao gồm tài liệu giải thích (có thể là chi tiết
Đây là phản hồi lỗi máy chủ chung. Hầu hết các khung web sẽ gửi mã trạng thái này nếu chúng chạy mã xử lý yêu
Máy khách đã cố gắng sử dụng một tính năng của HTTP (có thể là một tính năng mở rộng) mà máy chủ không hỗ trợ.
Trường hợp phổ biến nhất là khi máy khách cố gắng thực hiện một yêu cầu sử dụng phương thức HTTP mở rộng như
PATCH, phương thức mà máy chủ web đơn giản không hỗ trợ. Điều này tương tự với mã phản hồi 405 (Phương thức
không được phép), nhưng 405 ngụ ý rằng máy khách đang sử dụng một phương thức được công nhận trên một tài
nguyên không hỗ trợ nó. Mã phản hồi là 501 có nghĩa là máy chủ hoàn toàn không nhận ra phương thức này.
Bạn sẽ chỉ nhận được mã phản hồi này từ proxy HTTP. Nó chỉ ra rằng đã xảy ra sự cố với proxy hoặc giữa proxy
và máy chủ ngược dòng chứ không phải sự cố trên máy chủ ngược dòng.
Nếu proxy hoàn toàn không thể kết nối với máy chủ ngược dòng thì mã phản hồi sẽ là 504 (Hết thời gian chờ
cổng) .
Mã trạng thái này có nghĩa là máy chủ HTTP đã hoạt động nhưng ứng dụng cơ bản của API không hoạt động bình
thường. Nguyên nhân rất có thể là do thiếu tài nguyên: có quá nhiều yêu cầu được gửi đến cùng một lúc để API
Vì các yêu cầu lặp lại của khách hàng có thể là nguyên nhân gây ra sự cố nên máy chủ HTTP luôn có tùy chọn từ
chối chấp nhận yêu cầu của khách hàng, thay vì chỉ chấp nhận yêu cầu đó để gửi mã phản hồi 503.
Tiêu đề phản hồi: Máy chủ có thể gửi tiêu đề Retry-After cho khách hàng biết khi nào nên gửi lại yêu cầu.
Giống như 502 (Cổng xấu), bạn sẽ chỉ thấy điều này từ proxy HTTP. Mã trạng thái này báo hiệu rằng proxy
Máy chủ không hỗ trợ phiên bản HTTP mà máy khách đang cố sử dụng. Có thể bạn sẽ không thấy mã trạng thái
này cho đến khi HTTP 2.0 được công bố. Thậm chí khi đó, bạn có thể chỉ nhìn thấy nó khi cố gắng sử dụng
các tính năng HTTP 2.0 trên máy chủ HTTP 1.1.
Phần thân thực thể: Phải chứa tài liệu mô tả phiên bản HTTP nào mà máy chủ hỗ trợ.
Mã trạng thái 511 là một nỗ lực nhằm làm cho các cổng bị khóa bớt khó chịu hơn. Cổng bị khóa là trang web
chiếm quyền điều khiển trình duyệt web của bạn khi bạn cố gắng sử dụng mạng không dây trong quán cà phê
hoặc phòng khách sạn. Bất kể bạn yêu cầu trang web nào, cổng bị khóa sẽ cung cấp mã trạng thái 200 (OK)
cùng với một trang cho bạn biết cách thanh toán cho quyền truy cập Internet của bạn. Đôi khi cổng cung
cấp mã trạng thái 302 (Đã tìm thấy) và chuyển hướng trình duyệt đến một trang cho bạn biết cách thanh
Khi điều này xảy ra trong trình duyệt web của bạn, điều đó thật khó chịu, nhưng bạn là một con người. Bạn
có thể đọc trang web và tìm ra cách truy cập Web phù hợp. Khi điều này xảy ra với ứng dụng khách API của
bạn, điều đó thật nguy hiểm. Đối với ứng dụng khách tự động, có vẻ như API đã ngừng hoạt động và được
thay thế bằng một tài liệu HTML khó đọc có thể có nội dung "xin lỗi, chúng tôi đã đóng cửa". Điều này sẽ
làm hỏng máy khách, có khả năng khiến dữ liệu của nó ở trạng thái không nhất quán.
Mã trạng thái 511 không giúp ứng dụng khách API vượt qua cổng bị khóa dễ dàng hơn nhưng nó mang lại cho
khách hàng cơ hội tìm hiểu điều gì đang xảy ra và thoát ra một cách duyên dáng, thay vì hoảng sợ và gặp
sự cố.
Việc cung cấp mã trạng thái 511 yêu cầu nhà phát triển cổng bị khóa phải quan tâm đến trải nghiệm người
dùng, vì vậy tôi không mong đợi nó sẽ sớm được sử dụng rộng rãi. Nhưng việc đoán trước mã trạng thái 511
ở phía máy khách có thể giúp bạn tránh được trường hợp xấu nhất nếu ai đó kích hoạt ứng dụng khách API
PHỤ LỤC B
Codex tiêu đề
Tiêu đề HTTP là các bit siêu dữ liệu mô tả ngữ nghĩa giao thức của yêu cầu hoặc phản
hồi HTTP. Một số tiêu đề, như If-None-Match, chỉ được sử dụng trong các yêu cầu.
Đó là cách khách hàng thông báo cho máy chủ cách xử lý yêu cầu. Một số, như ETag, chỉ
được sử dụng trong phản hồi. Chúng là cách máy chủ truyền tải thông tin về cách xử lý
yêu cầu hoặc thông tin về tài nguyên cơ bản không có trong bản trình bày. Một số tiêu
đề có thể được sử dụng trong yêu cầu hoặc phản hồi, chẳng hạn như Loại nội dung cực
kỳ quan trọng , chứa loại phương tiện của nội dung thực thể.
Có hai hướng dẫn tuyệt vời về tiêu đề HTTP tiêu chuẩn. Một cái trong RFC 2616, chính
tiêu chuẩn HTTP và cái còn lại được in, trong Phụ lục C của HTTP: Hướng dẫn dứt khoát
của David Gourley và Brian Totty (O'Reilly). Trong phụ lục này, tôi sẽ đưa ra một mô
tả có phần chiếu lệ về các tiêu đề HTTP tiêu chuẩn, nhằm hướng tới việc sử dụng chúng
trong các API RESTful, trái ngược với các ứng dụng dựa trên HTTP khác như trang web
và proxy HTTP.
Tạo một phương thức HTTP hoặc mã trạng thái mới là một vấn đề rất lớn. Về cơ bản nó
yêu cầu viết RFC. Nhưng bất kỳ ai chạy máy chủ HTTP đều được phép xác định tiêu đề
HTTP của riêng họ. AtomPub xác định tiêu đề HTTP có tên Slug (được đề cập trong phần
sắp tới). Amazon xác định các tiêu đề như X-amz-acl và X-amz-date cho API S3 của mình.
Trong Dịch vụ web RESTful, tôi đã đưa ra một số lời khuyên về thời điểm xác định tiêu
đề HTTP tùy chỉnh và đặt tên cho nó. Trong vài năm qua, tôi đã thay đổi quan điểm về
cả hai điều này. Có lẽ bạn không nên tạo tiêu đề HTTP mới.
Tiêu đề HTTP mới là phần mở rộng của HTTP, giống như phương thức HTTP hoặc mã trạng
thái mới. Nếu bạn tạo tiêu đề mới, bạn phải ghi lại tiêu đề đó theo cách HTTP hiện có
317
Machine Translated by Google
các tiêu đề được ghi lại: với một lượng lớn tài liệu được diễn đạt chính xác mà con người có thể
đọc được. Sự khác biệt là khi người dùng nỗ lực tìm hiểu về tiêu đề HTTP tùy chỉnh của bạn, họ
không thể áp dụng kiến thức đó cho các máy chủ HTTP khác. Tiêu đề tùy chỉnh của bạn là tiêu chuẩn
Tin vui là nhiều trường hợp sử dụng tiêu đề HTTP mới không còn được áp dụng nữa.
Các định dạng dữ liệu Hypermedia ngày càng nhiều và linh hoạt hơn so với vài năm trước. Thông tin
từng đi vào tiêu đề tùy chỉnh giờ đây có thể đi thẳng vào phần trình bày. Nếu bạn cần thêm ngữ
nghĩa ứng dụng mới vào loại phương tiện hiện có, bạn có thể đặt thông tin đó vào cấu hình máy có
Bạn chỉ nên tạo tiêu đề HTTP mới nếu bạn thấy thiếu thứ gì đó trong chính giao thức HTTP. Liệu
thế giới có trở thành một nơi tốt đẹp hơn nếu tiêu đề của bạn trở thành tiện ích mở rộng tiêu
chuẩn cho HTTP không? Trong trường hợp đó, hãy tiếp tục và xác định tiêu đề mới. Có thể nó sẽ trở
thành một tiện ích mở rộng tiêu chuẩn, giống như tiêu đề Liên kết .
Về cách đặt tên: Tôi thường khuyên rằng tên tiêu đề tùy chỉnh nên bắt đầu bằng chuỗi X- cho “tiện
ích mở rộng”. Nếu bạn muốn gọi tiêu đề tùy chỉnh của mình là My-Header, tôi khuyên bạn nên gọi nó
là X-My-Header . RFC 6648 đã thay đổi suy nghĩ của tôi. Bạn không nên làm điều này. Chỉ cần đi
với My-Header.
Bài học rút ra từ các giao thức khác (như được mô tả trong RFC 6646) là tiền tố X- rắc rối hơn
giá trị của nó. Nếu tiêu đề HTTP tùy chỉnh của bạn từng được chuẩn hóa, bạn sẽ không thể xóa X-
vì điều đó sẽ phá vỡ tất cả các ứng dụng khách hiện có. Điều này có nghĩa là tiền tố X- không chỉ
ra sự hiện diện của tiện ích mở rộng một cách đáng tin cậy. Vì X- không phục vụ mục đích được
thiết kế nên không có lý do gì để sử dụng nó. Chỉ cần chọn một cái tên hay, độc đáo để bắt đầu.
tiêu đề
Đây là 46 tiêu đề được liệt kê trong RFC 2616, cũng như 8 tiêu đề được xác định trong RFC mở rộng
và Bản nháp Internet. Tôi sẽ trình bày một phần ngắn cho mỗi tiêu đề, cho biết liệu nó có được
tìm thấy trong các yêu cầu, phản hồi HTTP hay cả hai hay không. Tôi sẽ đưa ra ý kiến của mình về
mức độ hữu ích của tiêu đề đối với API. Tôi sẽ mô tả ngắn gọn về tiêu đề, mô tả này sẽ dài hơn
một chút đối với những tiêu đề phức tạp hoặc đặc biệt quan trọng. Tôi sẽ không đi sâu vào chi
tiết về giá trị tiêu đề sẽ như thế nào. Tôi nghĩ bạn thông minh và bạn có thể tra cứu thông tin
chi tiết hơn khi cần thiết.
Trừ khi có ghi chú khác, định nghĩa chính thức của tiêu đề có thể được tìm thấy trong RFC 2616.
Loại chấp
Máy khách gửi tiêu đề Chấp nhận để cho máy chủ biết loại phương tiện nào nó muốn máy chủ sử dụng cho các biểu
diễn của nó. Đây là kỹ thuật “thương lượng nội dung” mà tôi đã đề cập trong Chương 11. Một khách hàng có thể
muốn một tài liệu HAL ở định dạng XML (Chấp nhận: application/hal+xml); người khác có thể muốn biểu diễn
HAL+JSON của cùng một tài liệu HAL (Chấp nhận: application/hal+json).
Nếu bạn triển khai trình phân tích cú pháp cho tiêu đề này (hoặc bất kỳ tiêu đề Accept-* nào khác ), hãy xem
RFC 2616 để biết chi tiết. Định dạng phức tạp hơn nhiều so với bạn nghĩ.
Loại bộ ký tự chấp
Máy khách gửi tiêu đề Accept-Charset để cho máy chủ biết mã hóa ký tự nào nó muốn máy chủ sử dụng trong các
biểu diễn của nó. Một khách hàng có thể muốn bản trình bày của một tài nguyên chứa văn bản tiếng Nhật được mã
hóa theo UTF-8; người khác có thể muốn mã hóa Shift-JIS của cùng một dữ liệu.
Cá nhân tôi nghĩ mọi người nên sử dụng UTF-8 hoặc UTF-16 cho mọi thứ.
Máy khách gửi tiêu đề Accept-Encoding để thông báo cho máy chủ rằng nó có thể tiết kiệm một số băng thông bằng
cách nén nội dung thực thể phản hồi bằng thuật toán nổi tiếng như gzip. Mặc dù tên như vậy nhưng điều này
Giá trị của Mã hóa chấp nhận được gọi là “mã hóa nội dung”. IANA lưu giữ sổ đăng ký mã hóa nội dung được chấp
nhận tại http://www.iana.org/taskments/http-parameters/ http-parameters.xml. Nói chung, mã hóa nội dung chỉ
Tiêu đề | 319
Machine Translated by Google
Máy khách gửi tiêu đề Ngôn ngữ chấp nhận để cho máy chủ biết ngôn ngữ của con người mà nó muốn máy chủ
sử dụng trong các biểu diễn của nó. Tất nhiên, điều này không ảnh hưởng đến định dạng nhưng nó có thể ảnh
hưởng đến dữ liệu.
Giá trị cho Ngôn ngữ chấp nhận được gọi là thẻ ngôn ngữ. Có thể bạn đã quen thuộc với một số thẻ ngôn
ngữ: tiếng Anh là en và tiếng Anh Mỹ cụ thể là en-us. RFC 5646 đặt ra định dạng cho thẻ ngôn ngữ và IANA
lưu giữ sổ đăng ký ngôn ngữ (en) và vùng (chúng tôi) ở dạng máy có thể đọc được tại trang IANA này.
Máy chủ gửi tiêu đề này để cho biết rằng nó hỗ trợ HTTP GET một phần (xem Chương 11) cho một tài nguyên.
Điều này chỉ xuất hiện khi quá trình tải xuống bản trình bày của khách hàng bị gián đoạn.
Nếu máy chủ đặt tiêu đề Phạm vi chấp nhận trong phản hồi ban đầu, máy khách sẽ biết rằng nó có thể đưa
ra yêu cầu thứ hai tới cùng một URL, cung cấp tiêu đề Phạm vi thích hợp .
Sau đó, khách hàng có thể khởi động lại quá trình tải xuống tại thời điểm bị gián đoạn và không phải tải
Loại
Nếu nội dung thực thể phản hồi không mới từ máy chủ, thì tiêu đề Tuổi là thước đo khoảng thời gian cách
đây bao lâu, tính bằng giây, nội dung thực thể đó đã rời khỏi máy chủ. Tiêu đề này thường được đặt bởi
bộ đệm HTTP, để khách hàng biết rằng nó có thể nhận được bản sao cũ của bản trình bày.
Cho phép
Tôi thảo luận ngắn gọn về tiêu đề này trong Chương 3. Nó được gửi để đáp lại yêu cầu OPTIONS và cho khách
hàng biết một chút về ngữ nghĩa giao thức của tài nguyên: cụ thể là phương thức HTTP nào tài nguyên này
sẽ phản hồi.
Tiêu đề này không quan trọng lắm, vì hypermedia tạo ra cơ chế khám phá tốt hơn nhiều so với phương pháp
OPTIONS. Nhưng một số API thực hiện hỗ trợ cho TÙY CHỌN.
Ủy quyền
Tiêu đề yêu cầu này chứa thông tin xác thực ủy quyền, chẳng hạn như tên người dùng và mật khẩu, mà
khách hàng đã mã hóa theo sơ đồ đã thỏa thuận nào đó. Máy chủ giải mã thông tin đăng nhập và quyết định
Đây là tiêu đề ủy quyền duy nhất bạn cần (ngoại trừ Ủy quyền proxy, hoạt động ở cấp độ khác), vì nó
có thể mở rộng. Lược đồ phổ biến nhất là OAuth và HTTP Basic, nhưng lược đồ có thể là bất kỳ lược đồ
Có một số tiêu đề xác thực khác hoạt động dựa trên Xác thực, đặc biệt là X-WSSE, nhưng những tiêu chuẩn
đó gần như đã chết nên tôi không đề cập đến chúng trong cuốn sách này.
Tiêu đề này chứa một chỉ thị tới bất kỳ bộ đệm nào giữa máy khách và máy chủ (bao gồm cả bộ đệm cục bộ
trên chính máy khách hoặc máy chủ). Nó nêu rõ các quy tắc về cách dữ liệu sẽ được lưu vào bộ đệm và
khi nào dữ liệu đó sẽ được xóa khỏi bộ đệm. Đây là một tiêu đề rất phức tạp, nhưng tôi sẽ trình bày
các chỉ thị bộ nhớ đệm cơ bản nhất (“bộ nhớ đệm” và “không bộ nhớ đệm”) trong Chương 11.
Sự liên quan
Hầu hết phản hồi HTTP là giao tiếp từ máy chủ đến máy khách. Những người trung gian như người được ủy
quyền có thể xem phản hồi nhưng không có gì trong đó nhằm vào họ. Nhưng máy chủ có thể chèn các tiêu
đề bổ sung nhằm vào proxy và một proxy có thể chèn các tiêu đề nhắm vào proxy tiếp theo trong chuỗi.
Khi điều này xảy ra, các tiêu đề đặc biệt sẽ được đặt tên trong tiêu đề Kết nối . Các tiêu đề này áp
dụng cho kết nối TCP giữa máy này với máy khác, không áp dụng cho kết nối HTTP giữa máy chủ
Tiêu đề | 321
Machine Translated by Google
và khách hàng. Trước khi chuyển phản hồi, proxy có nhiệm vụ xóa các tiêu đề đặc biệt và
chính tiêu đề Kết nối . Tất nhiên, nó có thể thêm các thông tin liên lạc đặc biệt của
riêng nó và một tiêu đề Kết nối mới nếu muốn.
Đây là một ví dụ nhanh vì nó không liên quan nhiều đến cuốn sách này. Máy chủ có thể
gửi ba tiêu đề HTTP này trong phản hồi thông qua proxy:
Proxy-Directive là tiêu đề HTTP tùy chỉnh. Máy chủ và proxy hiểu nó, nhưng máy khách có
thể không. Proxy sẽ xóa Chỉ thị Proxy và Kết nối, đồng thời gửi một tiêu đề còn lại cho
máy khách:
Nếu bạn đang viết một ứng dụng khách và không sử dụng proxy, giá trị duy nhất bạn có
thể thấy cho Kết nối là đóng. Điều đó chỉ nói rằng máy chủ sẽ đóng kết nối TCP sau khi
hoàn thành yêu cầu này.
Tiêu đề Bố trí nội dung thường được sử dụng để chỉ ra rằng máy khách nên lưu nội dung
thực thể dưới dạng tệp, thay vì xử lý nó dưới dạng biểu diễn. Khi sử dụng, nó trông
giống như thế này:
Bất kỳ API nào có thể lưu trữ các tệp đã tải lên đều phải sử dụng Bố trí nội dung để
phân biệt các tệp đã tải lên với các tài liệu do API tạo ra. Nếu API phân phát tài liệu
không đúng định dạng, điều đó có nghĩa là có lỗi trong API—trừ khi tài liệu không đúng
định dạng được khách hàng tải lên và API chỉ thể hiện chính xác những gì đã được tải lên.
Trong ví dụ này, phần đính kèm giá trị cho biết nội dung thực thể này là phần đính kèm
và tham số tên tệp gợi ý tên tệp nào sẽ lưu tài liệu dưới dạng. Tham số đó mở ra một
loạt sâu, về mặt bảo mật, đó là lý do tại sao tiêu đề Bố trí nội dung bị loại trừ rõ
ràng khỏi tiêu chuẩn HTTP. Khi viết một ứng dụng khách tôn trọng Bố trí nội dung hoặc
khi cho phép ứng dụng khách API đặt tên cho các tệp họ tải lên, hãy xem lời khuyên trong
RFC 6266 và hãy cẩn thận.
đề phản hồi.
Tiêu đề phản hồi này là đối trọng của tiêu đề yêu cầu Mã hóa chấp nhận. Tiêu đề yêu cầu yêu cầu máy chủ nén
nội dung thực thể bằng một thuật toán nhất định.
Tiêu đề này cho máy khách biết thuật toán nào, nếu có, máy chủ thực sự đã sử dụng.
Giống như Mã hóa chấp nhận, giá trị của tiêu đề này được gọi là “mã hóa nội dung” và IANA lưu giữ sổ đăng ký
các mã hóa nội dung được chấp nhận tại http://www.iana.org/task-ments/http-parameters/ http-parameter.xml. Về
lý thuyết, mã hóa nội dung có thể là bất kỳ loại chuyển đổi dữ liệu có thể đảo ngược nào, nhưng tất cả các mã
đề phản hồi.
Tiêu đề phản hồi này là đối trọng với tiêu đề yêu cầu Ngôn ngữ chấp nhận hoặc với một biến tương ứng được đặt
trong URI của tài nguyên. Nó chỉ rõ ngôn ngữ tự nhiên mà con người phải hiểu để hiểu được ý nghĩa của thực thể-
cơ thể.
Giống như tất cả các tiêu đề Accept-* và phản hồi tương đương của chúng, tiêu đề này có thể chứa nhiều giá
trị. Nếu nội dung thực thể là một bộ phim bằng tiếng Quan Thoại có phụ đề tiếng Nhật thì giá trị của Content-
Language có thể là zh-guoyu,jp. Nếu một cụm từ tiếng Anh xuất hiện trong phim thì en có thể sẽ không hiển thị
Tiêu đề phản hồi này cung cấp kích thước của phần thân thực thể tính bằng byte. Điều này quan trọng vì hai lý
do: thứ nhất, khách hàng có thể đọc trước phần này và chuẩn bị cho một thực thể nhỏ hoặc một thực thể lớn.
Thứ hai, khách hàng có thể thực hiện yêu cầu HEAD để tìm hiểu xem phần thân thực thể lớn đến mức nào mà không
thực sự yêu cầu nó. Giá trị của Độ dài nội dung có thể ảnh hưởng đến quyết định của khách hàng về việc tìm
nạp toàn bộ nội dung thực thể, tìm nạp một phần của nó bằng Phạm vi hoặc hoàn toàn không tìm nạp nó.
Tiêu đề | 323
Machine Translated by Google
Tiêu đề này cho khách hàng biết URL chuẩn của tài nguyên mà nó yêu cầu. Không giống như giá trị của tiêu đề
Vị trí , giá trị này hoàn toàn mang tính thông tin. Khách hàng sẽ không bắt đầu sử dụng URL mới.
Điều này chủ yếu hữu ích đối với các API gán các URL khác nhau cho các cách thể hiện khác nhau của một tài
nguyên. Nếu khách hàng muốn liên kết đến đại diện cụ thể thu được thông qua đàm phán nội dung, thì khách
hàng có thể sử dụng URI được cung cấp trong Vị trí nội dung. Vì vậy, nếu bạn yêu cầu /documents/104 và sử
dụng các tiêu đề Accept và Accept-Language để chỉ định cách trình bày HTML được viết bằng tiếng Anh, bạn có
thể nhận được phản hồi chỉ định /documents/104.html.en làm giá trị cho Nội dung -Vị trí. Đó là liên kết đến
Lưu ý rằng tiêu đề này là một điều khiển siêu phương tiện đơn giản. Nó hoạt động theo cách tương tự như một
Nội dung-MD5
Đây là tổng kiểm tra mật mã của phần thân thực thể. Máy khách có thể sử dụng điều này để kiểm tra xem phần
thân thực thể có bị hỏng trong quá trình vận chuyển hay không. Kẻ tấn công (chẳng hạn như kẻ trung gian)
có thể thay đổi nội dung thực thể và thay đổi tiêu đề Content-MD5 cho phù hợp, do đó, điều này không tốt cho
Khi máy khách thực hiện một yêu cầu GET một phần với tiêu đề Yêu cầu phạm vi , tiêu đề phản hồi này cho biết
Tiêu đề HTTP nổi tiếng nhất và có lẽ là quan trọng nhất, Content-Type cung cấp loại phương tiện của nội dung
• Nó xác định trình phân tích cú pháp nào mà người nhận sẽ sử dụng để phân tích phần thân thực thể.
• Nó thường xác định ngữ nghĩa giao thức của biểu diễn—phần nào của biểu diễn là các điều khiển
siêu phương tiện và những yêu cầu HTTP nào có thể được kích hoạt bằng cách kích hoạt các điều
khiển đó.
• Nó cũng có thể xác định ngữ nghĩa ứng dụng của biểu diễn—ý nghĩa của biểu diễn đó xét về các
Có nhiều cách khác để truyền tải ngữ nghĩa ứng dụng và giao thức, chẳng hạn như liên kết đến hồ sơ,
nhưng Kiểu nội dung là cách chính. Đây là lý do tại sao việc phân phát ứng dụng/json làm loại phương
tiện của bạn là một ý tưởng tồi . Bạn đang bỏ qua một cơ hội lớn.
Khi cung cấp tài liệu được mô tả theo loại phương tiện và cấu hình, bạn nên cung cấp tiêu đề Liên kết
Bánh quy
Tầm quan trọng: Cao trên web con người, thấp trong thế giới API.
Đây có lẽ là tiêu đề HTTP nổi tiếng thứ hai, sau Content-Type, nhưng nó không nằm trong tiêu chuẩn
Cookie là một thỏa thuận giữa máy khách và máy chủ trong đó máy chủ sẽ lưu trữ một số trạng thái bán
liên tục ở phía máy khách bằng cách sử dụng tiêu đề Set-Cookie (sẽ nói thêm về điều này trong phần
sắp tới). Sau khi khách hàng nhận được cookie, nó phải trả lại cookie đó cùng với mọi yêu cầu HTTP
tiếp theo tới máy chủ đó, bằng cách đặt tiêu đề Cookie một lần cho mỗi cookie của nó. Vì dữ liệu được
gửi ẩn trong tiêu đề HTTP với mọi yêu cầu nên có vẻ như máy khách và máy chủ đang ở trạng thái chia
sẻ.
Cookie có tiếng xấu trong vòng kết nối REST vì hai lý do. Đầu tiên, “trạng thái” mà chúng chứa thường
chỉ là ID phiên: một khóa chữ và số ngắn liên kết với cấu trúc dữ liệu lớn hơn nhiều trên máy chủ.
Điều này phá hủy nguyên tắc không trạng thái vì trạng thái ứng dụng đang được lưu giữ trên máy chủ.
Tinh tế hơn, khi khách hàng chấp nhận cookie, họ phải gửi cookie đó cùng với tất cả các yêu cầu tiếp
theo trong một thời gian nhất định. Máy chủ thông báo cho khách hàng rằng nó không thể thực hiện các
yêu cầu mà nó đã tạo trước cookie nữa. Điều này cũng vi phạm nguyên tắc không quốc tịch.
Nếu bạn phải sử dụng cookie, hãy đảm bảo bạn lưu trữ tất cả trạng thái ở phía máy khách. Nếu không,
bạn sẽ mất rất nhiều lợi ích về khả năng mở rộng của REST.
Ngày
Tiêu đề | 325
Machine Translated by Google
Tầm quan trọng: Cao đối với yêu cầu, cần thiết để đáp ứng.
Là tiêu đề yêu cầu, điều này thể hiện thời gian trên máy khách tại thời điểm yêu cầu được gửi. Là
tiêu đề phản hồi, nó thể hiện thời gian trên máy chủ tại thời điểm yêu cầu được thực hiện. Phiên
bản tiêu đề phản hồi của Ngày được bộ nhớ đệm sử dụng khi tính toán xem tài liệu được lưu trong
bộ nhớ đệm có còn mới hay không.
Loại
Giá trị của ETag là một chuỗi mờ biểu thị một phiên bản cụ thể của biểu diễn.
Bất cứ khi nào cách biểu thị thay đổi thì ETag cũng sẽ thay đổi.
Máy chủ nên gửi ETag để đáp lại yêu cầu GET bất cứ khi nào có thể. Như tôi đã trình bày trong
Chương 11, khách hàng có thể thực hiện yêu cầu GET có điều kiện bằng cách gửi giá trị ETag trước
đó làm giá trị của tiêu đề yêu cầu If-None-Match . Nếu bản trình bày không thay đổi thì ETag cũng
không thay đổi và máy chủ có thể tiết kiệm thời gian và băng thông bằng cách không gửi lại bản
trình bày.
Trình điều khiển chính của các yêu cầu GET có điều kiện là tiêu đề phản hồi được sửa đổi lần cuối
đơn giản hơn và đối tác yêu cầu của nó là If-Modified-Since. Mục đích chính của ETag là cung cấp
tuyến phòng thủ thứ hai. Nếu một biểu diễn thay đổi hai lần trong một giây, nó sẽ chỉ nhận một
giá trị cho Last-Modified-Since, nhưng có hai giá trị khác nhau cho ETag.
Nếu có một trung gian giữa máy chủ và máy khách sửa đổi các biểu diễn của bạn (chẳng hạn như mô-
đun mod_compress của Apache , nén các biểu diễn một cách trong suốt), thì trung gian đó cũng sẽ
thay đổi giá trị của ETag, theo những cách có thể phá vỡ các yêu cầu có điều kiện.
Loại mong
Tầm quan trọng: Trung bình nhưng hiếm khi được sử dụng.
Tiêu đề này được sử dụng để báo hiệu yêu cầu xem trước khi bạn nhảy (được đề cập trong Chương 11).
Máy chủ sẽ gửi mã phản hồi 100 (Tiếp tục) nếu máy khách “nhảy” về phía trước và đưa ra yêu cầu
thực sự. Nó sẽ gửi mã phản hồi 417 (Kỳ vọng không thành công) nếu khách hàng không nên “nhảy”.
Loại hết
Tiêu đề này cho máy khách hoặc proxy giữa máy chủ và máy khách biết rằng nó có thể lưu trữ phản hồi HTTP
(không chỉ phần nội dung thực thể!) cho đến một thời điểm nhất định. Điều này rất hữu ích vì ngay cả một
HTTP GET có điều kiện mà cuối cùng không làm gì cũng có chi phí chung của một yêu cầu HTTP. Bằng cách chú
ý đến Hết hạn, khách hàng có thể tránh được nhu cầu thực hiện bất kỳ yêu cầu HTTP nào—ít nhất là trong
Việc sử dụng chỉ thị bộ đệm ẩn tối đa của tiêu đề Kiểm soát bộ đệm thường dễ dàng hơn .
(Đó là cái tôi đã trình bày ở Chương 11.) Tức là, nói “sự biểu diễn này sẽ ổn trong khoảng một giờ” thì
dễ hơn là tính thời gian chính xác một giờ kể từ bây giờ.
Nhưng nếu máy chủ biết chính xác khi nào một biểu diễn sẽ thay đổi (vì nó thay đổi vào cùng một thời điểm
mỗi giờ, mỗi ngày hoặc mỗi tuần), thì Expires sẽ tốt hơn.
Khách hàng nên coi giá trị Hết hạn làm hướng dẫn sơ bộ chứ không phải như một lời hứa rằng nội dung thực
Từ
Loại: Tiêu đề yêu cầu.
Tiêu đề này hoạt động giống như tiêu đề Từ trong thư email. Nó cung cấp một địa chỉ email được liên kết
với người đưa ra yêu cầu. Điều này không bao giờ được sử dụng trên World Wide Web vì những lo ngại về
quyền riêng tư và nó không bao giờ được sử dụng trong thế giới API, nơi chúng tôi có các cách khác để xác
Chủ nhà
Tiêu đề này chứa phần tên miền của URL yêu cầu. Nếu khách hàng thực hiện yêu cầu GET cho http://
www.example.com/page.html thì URL thực sự được yêu cầu là /page.html và giá trị của tiêu đề Máy chủ là
Từ quan điểm của khách hàng, điều này có vẻ giống như một tiêu đề lạ cần được yêu cầu. Điều này là bắt
buộc vì máy chủ HTTP có thể lưu trữ bất kỳ số lượng tên miền nào trên một địa chỉ IP.
Tính năng này được gọi là “lưu trữ ảo dựa trên tên” và nó giúp người sở hữu nhiều tên miền không phải mua
một máy tính và/hoặc card mạng riêng cho mỗi tên miền.
Vấn đề với dịch vụ lưu trữ ảo dựa trên tên là khi máy khách mở kết nối TCP, nó sẽ kết nối với máy chủ dựa
trên địa chỉ IP chứ không phải tên miền. Không có
Tiêu đề | 327
Machine Translated by Google
tiêu đề Máy chủ chứa tên miền, máy chủ HTTP sẽ không biết máy chủ ảo nào của nó là mục tiêu
Nếu khớp
Tiêu đề này được mô tả tốt nhất theo các tiêu đề khác. Nó được sử dụng như If-Unmodified-
Vì (được mô tả sau), để thực hiện các hành động HTTP không phải GET có điều kiện—nói chung
là để tránh sự cố mất cập nhật mà tôi đã đề cập trong Chương 11. Nhưng nếu If-Unmodified-
Since lấy thời gian làm giá trị, thì tiêu đề này lấy ETag làm giá trị của nó .
Nếu-Sửa đổi-Kể từ
Tiêu đề yêu cầu này là xương sống của HTTP GET có điều kiện. Giá trị của nó là giá trị mà
khách hàng tìm thấy trong tiêu đề phản hồi được sửa đổi lần cuối khi nó thực hiện yêu cầu
GET trước đó đối với tài nguyên này. Khi máy khách gửi giá trị đó dưới dạng If-Modified-
Since, nó sẽ chỉ yêu cầu nhận thông tin đại diện nếu thông tin đại diện đã thay đổi kể từ
yêu cầu cuối cùng.
Nếu trên thực tế, phần trình bày đã thay đổi kể từ yêu cầu cuối cùng đó, thì ngày Sửa đổi
lần cuối mới của nó sẽ gần đây hơn ngày trước đó. Điều đó có nghĩa là điều kiện If-Modified-
Since được đáp ứng và máy chủ sẽ gửi bản trình bày mới. Nếu tài nguyên không thay đổi, ngày
sửa đổi lần cuối vẫn giữ nguyên và điều kiện If-Modified-Since không thành công. Máy chủ
gửi mã phản hồi 304 (Không được sửa đổi) và không có nội dung thực thể. Nghĩa là, HTTP GET
có điều kiện sẽ thành công nếu điều kiện này không thành công.
Vì Last-Modified chỉ chính xác trong vòng một giây nên HTTP GET có điều kiện đôi khi có thể
cho kết quả sai nếu nó chỉ dựa vào If-Modified-Since. Đây là lý do chính tại sao chúng tôi
Tiêu đề này cũng được sử dụng trong HTTP GET có điều kiện. Giá trị của nó được lấy từ tiêu đề phản hồi
ETag được gửi cùng với yêu cầu GET trước đó.
Nếu ETag của đại diện đã thay đổi kể từ yêu cầu cuối cùng đó, điều kiện If-None-Match thành công và máy
chủ sẽ gửi đại diện mới. Nếu ETag vẫn giống như trước, điều kiện không thành công và máy chủ sẽ gửi mã
phản hồi 304 (“Không được sửa đổi”) mà không có nội dung thực thể.
Loại phạm vi
Tiêu đề này được sử dụng để thực hiện yêu cầu GET một phần có điều kiện . Giá trị của tiêu đề đến từ tiêu
đề phản hồi ETag hoặc Lần sửa đổi cuối cùng từ yêu cầu phạm vi trước đó.
Máy chủ chỉ gửi phạm vi mới nếu phần đó của nội dung thực thể đã thay đổi. Mặt khác, máy chủ sẽ gửi 304
(Không được sửa đổi), ngay cả khi có gì đó đã thay đổi ở nơi khác trong nội dung thực thể.
GET một phần có điều kiện không được sử dụng thường xuyên, bởi vì rất khó có khả năng máy khách sẽ tìm
nạp một vài byte từ một biểu diễn lớn hơn và sau đó cố gắng chỉ tìm nạp những byte tương tự đó sau đó.
Thông thường, khách hàng sử dụng giá trị của tiêu đề phản hồi Last-Modified làm giá trị của tiêu đề yêu
cầu If-Modified-Since để thực hiện yêu cầu GET có điều kiện. Tiêu đề này cũng nhận giá trị Sửa đổi lần
cuối, nhưng nó thường được sử dụng để thực hiện các hành động HTTP ngoài GET thành các hành động có điều
kiện. Mục đích thường là để tránh vấn đề mất cập nhật mà tôi đã thảo luận ở Chương 11.
Nếu bạn đặt yêu cầu PUT hoặc PATCH có điều kiện theo If-Unmodified-Since, thì nếu người khác đã thay đổi
tài nguyên mà bạn không biết, yêu cầu của bạn sẽ luôn nhận được mã phản hồi là 412 (Điều kiện tiên quyết
không thành công). Bạn có thể tìm nạp lại bản trình bày và quyết định phải làm gì với phiên bản mới mà
người khác đã sửa đổi.
Tiêu đề này cũng có thể được sử dụng với GET. Xem phần thảo luận của tôi về tiêu đề Phạm vi để biết ví dụ.
Tiêu đề | 329
Machine Translated by Google
Tiêu đề này làm cho HTTP GET có điều kiện có thể thực hiện được. Nó cho khách hàng biết lần cuối
cùng biểu diễn thay đổi. Khách hàng có thể theo dõi ngày này và sử dụng nó trong tiêu đề If-
Trong các ứng dụng web, Last-Modified thường là thời gian hiện tại, điều này làm cho HTTP GET
có điều kiện trở nên vô dụng. API nên cố gắng làm tốt hơn, vì các ứng dụng khách API thường gửi
đi tấn công máy chủ của họ bằng các yêu cầu cho cùng một URL (đặc biệt là URL biển quảng cáo).
liên kết
Tiêu đề này phục vụ như một liên kết hypermedia có mục đích chung. Tôi đề cập đến tiêu đề này
nhiều lần trong cuốn sách, đặc biệt là trong Chương 4 và Chương 11. Giá trị của nó là một URL,
trong dấu ngoặc nhọn và sau đó là một số tham số (như rel) cung cấp ngữ cảnh cho URL. Ví dụ:
Mặc dù rel là tham số quan trọng nhất được liên kết với tiêu đề này, RFC 5988 xác định
một số tham số khác: hreflang, media, title, title* và type. Các tham số hreflang và
type chỉ định ngôn ngữ con người và loại phương tiện của liên kết đích, giống như trong
thẻ <a> của HTML. Các tham số title và title* là những cách khác nhau để cung cấp tiêu
đề mà con người có thể đọc được cho liên kết.
Tham số media hoạt động giống như thuộc tính media của thẻ <style> HTML : nó giải thích
phương tiện hiển thị nào có thể được sử dụng để hiển thị phần trình bày ở đầu bên kia
của liên kết (màn hình, bản in, chữ nổi, v.v.).
Mặc dù Liên kết thường là tiêu đề phản hồi nhưng có những trường hợp khách hàng cần gửi nó cùng
với một yêu cầu. Nếu một tài liệu yêu cầu một cấu hình để hiểu ngữ nghĩa ứng dụng của nó thì
ứng dụng khách POST, PUT hoặc PATCH tài liệu đó sẽ gửi tiêu đề Liên kết cùng với tài liệu. Giá
trị của Liên kết phải trỏ đến tài liệu hồ sơ và có rel="profile". Logic tương tự áp dụng cho
một tài liệu chỉ có ý nghĩa khi được kết hợp với ngữ cảnh JSON-LD.
Việc cung cấp cho tiêu đề Liên kết nhiều hơn một giá trị là hợp pháp :
Điều này cũng đúng với một số tiêu đề HTTP khác, nhưng Liên kết và Mẫu liên kết là những tiêu đề
Được xác định trong: Bản nháp Internet-Draft đã hết hạn “bản nháp-nottingham-link-mẫu”.
Tôi đã đề cập đến tiêu đề này trong Chương 11. Nó hoạt động giống như Link, ngoại trừ giá trị của
nó là Mẫu URI (RFC 5988). Điều này mang lại cho nó khả năng siêu phương tiện tương đương với một
dạng HTML có hành động = "GET". Điều đó linh hoạt hơn nhiều so với Link, có thể so sánh với thẻ
HTML <a> .
Tiêu đề Link-Template hỗ trợ tất cả các tham số của Link , cộng thêm một tham số nữa, “var-base,”
Vị trí
Loại: Tiêu đề phản hồi.
Đây là một trong hai tiêu đề HTTP được xác định trong RFC 2616 hoạt động như các liên kết
hypermedia. Cái còn lại, Nội dung-Vị trí, có ý nghĩa đơn giản, nhất quán, nhưng ý nghĩa của liên
Tiêu đề này được liên kết chặt chẽ với họ mã trạng thái 3xx (Chuyển hướng) và phần lớn sự nhầm lẫn
Vị trí có ý nghĩa hơi khác nhau đối với từng loại chuyển hướng:
• Khi yêu cầu của khách hàng tạo một tài nguyên hoàn toàn mới, mã phản hồi là 201 (Đã tạo) và
tiêu đề Vị trí là liên kết đến tài nguyên mới được tạo.
• Khi máy chủ không thể quyết định nên phân phát đại diện nào và mỗi đại diện có URL riêng, mã
trạng thái là 300 (+Nhiều lựa chọn+) và tiêu đề +Vị trí+ liên kết đến đại diện mà máy chủ ưa
thích: Điều này khác với đại diện tình huống phổ biến hơn
khi có nhiều biểu diễn, mỗi biểu diễn có URL riêng và khách hàng sử dụng thỏa thuận nội dung
để lựa chọn giữa chúng. Trong trường hợp đó, mã trạng thái là 200 (+OK+), +Location+ không
được cung cấp và +Content-Location+ trỏ đến URL chuẩn của đại diện mà khách hàng đã thương
lượng.
Tiêu đề | 331
Machine Translated by Google
• Khi yêu cầu của khách hàng khiến tài nguyên thay đổi URL của nó, mã phản hồi là 301 (Đã di chuyển vĩnh
viễn) và tiêu đề Vị trí là liên kết đến tài nguyên ban đầu tại vị trí mới.
• Khi máy khách đưa ra yêu cầu tới URL “sai”, nhưng máy chủ vẫn có thể tìm ra tài nguyên nào máy khách đang
đề cập đến, tiêu đề Vị trí là một liên kết đến URL “đúng”. Mã phản hồi có thể là 301, 302 (Đã tìm thấy),
307 (Chuyển hướng lại tạm thời) hoặc 308 (Chuyển hướng vĩnh viễn), tùy thuộc vào lý do chính xác tại sao
• Khi mã phản hồi là 303 (Xem phần khác), tài nguyên ở đầu kia của Vị trí không phải là đại diện cho tài
nguyên được yêu cầu; đó là thông báo giải thích cách xử lý yêu cầu. Điều này thường được sử dụng bởi các
tài nguyên phản hồi các yêu cầu POST nhưng không có đại diện của riêng chúng.
Tiêu đề này chủ yếu được sử dụng với phương thức TRACE, được sử dụng để theo dõi các proxy xử lý yêu cầu HTTP
của khách hàng. Tôi không đề cập đến TRACE trong cuốn sách này, nhưng là một phần của yêu cầu TRACE, Chuyển
tiếp tối đa được sử dụng để giới hạn số lượng proxy mà yêu cầu có thể được gửi qua.
Loại thực
Tiêu đề Pragma là một khe dành cho các chỉ thị đặc biệt giữa máy khách, máy chủ và các thiết bị trung gian như
proxy. Pragma chính thức duy nhất là no-cache, đã lỗi thời trong HTTP 1.1; nó giống như gửi giá trị no-cache
Bạn có thể xác định các pragma HTTP của riêng mình, nhưng thay vào đó, tốt hơn là bạn nên xác định các tiêu
đề HTTP của riêng mình. Thấy không, (Cũng không phải là bạn nên làm điều đó.)
Thích hơn
Tiêu đề Prefer cho phép máy khách truyền đạt các tùy chọn của mình tới máy chủ về nhiều vấn đề nhỏ
khác nhau không nằm trong tiêu chuẩn HTTP hoặc theo các quy tắc liên quan đến loại phương tiện. Bản
dự thảo Internet xác định Ưu tiên đề xuất sổ đăng ký tùy chọn IANA mà các tiêu chuẩn web khác có thể
thêm vào, nhưng nó cũng xác định sáu tùy chọn để xử lý ba vấn đề xuất hiện thường xuyên trong API:
• Tùy chọn xử lý=khoan dung yêu cầu máy chủ cố gắng xử lý yêu cầu ngay cả khi có những vấn đề nhỏ
về cú pháp hoặc ngữ nghĩa. Tùy chọn xử lý=nghiêm ngặt thì ngược lại: nó yêu cầu máy chủ gửi tình
trạng lỗi ngay khi tìm thấy ngay cả vấn đề nhỏ nhất.
• Tùy chọn phản hồi không đồng bộ cho phép máy chủ biết rằng nếu việc thực hiện yêu cầu mất nhiều
thời gian, máy khách muốn máy chủ gửi mã phản hồi 202 (Được chấp nhận) thay vì bắt máy khách phải
chờ phản hồi. Tùy chọn chờ có thể được đặt thành một số giây (ví dụ: chờ = 10), biểu thị khoảng
thời gian khách hàng sẵn sàng chờ phản hồi thực sự.
• Tùy chọn return=minimal được gửi cùng với yêu cầu tạo hoặc sửa đổi tài nguyên (PUT, POST hoặc
PATCH). Đó là cách khách hàng thông báo với máy chủ rằng nó không muốn có sự thể hiện đầy đủ về
tài nguyên tài nguyên mới hoặc đã sửa đổi. Tùy chọn return =ređại diện thì ngược lại. Điều đó có
nghĩa là máy khách muốn có một bản trình bày đầy đủ, ngay cả khi máy chủ thường không gửi một
Nếu bạn xác định các tùy chọn của riêng mình, hãy nhớ rằng chúng có cùng vấn đề với tiêu đề HTTP tùy
chỉnh. Tùy chọn mới là phần mở rộng cho HTTP. Bạn phải ghi lại nó thật chính xác, giống như cách các
ưu tiên khác được ghi lại. Tùy chọn mới của bạn sẽ là tiêu chuẩn tiền pháp định nên hầu hết khách hàng
sẽ không hỗ trợ nó. Nói chung, việc tạo một điều khiển hypermedia mới thường dễ dàng hơn việc xác định
Tầm quan trọng: Ít quan trọng hơn một chút so với Prefer.
Khi máy chủ nhận được yêu cầu sử dụng Ưu tiên và quyết định đáp ứng một số tùy chọn của khách hàng,
nó có thể đề cập đến những tùy chọn nào được cung cấp trong tiêu đề Tùy chọn-Áp dụng . Đôi khi, không
rõ liệu lỗi là do xử lý = nghiêm ngặt hay lỗi đó có xảy ra hay không; hoặc liệu phần thân thực thể
nhỏ vì return=minimal hay vì biểu diễn chỉ nhỏ. Tiêu đề Preference-Applied làm rõ điều đó.
Tiêu đề | 333
Machine Translated by Google
đề phản hồi.
Một số khách hàng (đặc biệt là trong môi trường công ty) chỉ có thể truy cập HTTP thông qua máy chủ
proxy. Một số máy chủ proxy yêu cầu xác thực. Tiêu đề này là cách yêu cầu xác thực của proxy. Nó được gửi
cùng với mã phản hồi 407 (Yêu cầu xác thực Proxy Au) và nó hoạt động giống như WWW-Authenticate, ngoại
trừ việc nó cho khách hàng biết cách xác thực bằng proxy chứ không phải với máy chủ web ở đầu bên kia.
Trong khi phản hồi cho thử thách Xác thực WWW được chuyển vào Cấp phép, thì phản hồi cho thử thách Xác
thực Proxy sẽ chuyển sang Cấp phép Proxy (xem phần tiếp theo). Một yêu cầu có thể cần bao gồm cả tiêu đề
Ủy quyền và Ủy quyền proxy : một tiêu đề để xác thực bằng API, tiêu đề còn lại để xác thực bằng proxy.
Vì hầu hết các API không bao gồm các proxy hiển thị trong kiến trúc của chúng nên tiêu đề này không liên
quan nhiều đến các chủ đề được đề cập trong cuốn sách này. Nhưng nó có thể phù hợp với một máy khách nếu
có một proxy giữa máy khách và phần còn lại của Web.
yêu cầu.
Tiêu đề này là một nỗ lực để nhận được yêu cầu thông qua proxy yêu cầu xác thực.
Nó hoạt động tương tự như Ủy quyền. Định dạng của nó phụ thuộc vào lược đồ được xác định trong Proxy-
Authenticate, giống như định dạng của Ủy quyền phụ thuộc vào lược đồ được xác định trong WWW-Authenticate.
Loại phạm
vi : Yêu cầu.
Tiêu đề này biểu thị nỗ lực của khách hàng chỉ yêu cầu một phần biểu diễn của tài nguyên (xem Chương 11).
Máy khách thường gửi tiêu đề này vì trước đó nó đã cố tải xuống một bản trình bày lớn nhưng đã bị cắt.
Bây giờ nó quay trở lại cho phần còn lại của phần trình bày. Do đó, tiêu đề này thường được kết hợp với
Trừ khi được sửa đổi-Vì. Nếu phần trình bày đã thay đổi kể từ yêu cầu cuối cùng của bạn, bạn sẽ cần NHẬN
nó ngay từ đầu.
Tầm quan trọng: Cao trên World Wide Web, thấp đối với API.
Khi bạn nhấp vào một liên kết trong trình duyệt web của mình, trình duyệt sẽ gửi một yêu cầu HTTP trong đó
giá trị của tiêu đề Người giới thiệu là URL của trang bạn vừa truy cập. Đó là URL “giới thiệu” ứng dụng
khách của bạn tới URI mà bạn hiện đang yêu cầu. Vâng, nó sai chính tả.
Mặc dù phổ biến trên web của con người nhưng tiêu đề này hiếm khi được sử dụng trong API. Nó có thể được sử
dụng để truyền tải một chút trạng thái ứng dụng (đường dẫn gần đây của máy khách thông qua API) đến máy chủ.
Tôi không coi tiêu đề Người giới thiệu là một liên kết hypermedia, mặc dù giá trị của nó luôn là một URL,
vì tiêu đề được gửi từ máy khách đến máy chủ. Liên kết Hypermedia chảy từ máy chủ đến máy khách.
Tiêu đề này thường đi kèm với mã phản hồi biểu thị lỗi: 413 (Thực thể yêu cầu quá lớn), 429 (Quá nhiều yêu
cầu) hoặc một trong các chuỗi 5xx (Lỗi phía máy chủ). Các mã này cho khách hàng biết rằng mặc dù máy chủ
không thể thực hiện yêu cầu ngay bây giờ nhưng nó có thể thực hiện yêu cầu tương tự sau đó. Giá trị của
tiêu đề Retry-After là thời gian máy khách nên thử lại hoặc số giây cần đợi.
Nếu sự cố là máy chủ bị quá tải và máy chủ chọn giá trị Thử lại sau của mọi máy khách bằng cách sử dụng các
quy tắc giống nhau thì điều đó chỉ đảm bảo rằng các máy khách đó sẽ thực hiện các yêu cầu tương tự theo
cùng một thứ tự sau đó một lát, khiến máy chủ lại bị quá tải. Máy chủ nên sử dụng một số kỹ thuật ngẫu nhiên
để thay đổi Retry-After, tương tự như khoảng thời gian chờ của Ethernet.
Đặt cookie
Tầm quan trọng: Cao trên World Wide Web, thấp đối với API.
Đây là một nỗ lực của máy chủ nhằm thiết lập một số trạng thái bán liên tục trong cookie ở phía máy khách.
Khách hàng phải gửi tiêu đề Cookie thích hợp cùng với tất cả các yêu cầu trong tương lai cho đến ngày hết
hạn của cookie. Khách hàng có thể bỏ qua tiêu đề này (và đó thường là một ý tưởng hay), nhưng không có gì
đảm bảo rằng các yêu cầu trong tương lai sẽ nhận được kết quả tốt.
Tiêu đề | 335
Machine Translated by Google
phản hồi trừ khi họ cung cấp tiêu đề Cookie . Điều này vi phạm nguyên tắc không trạng thái, đó là lý do
tại sao tôi không khuyên bạn nên sử dụng cookie trong API.
Loại
Tầm quan trọng: Khá cao, nhưng chỉ có trong API AtomPub.
Khi ứng dụng khách AtomPub đăng tài liệu nhị phân (chẳng hạn như ảnh) lên nguồn cấp dữ liệu, ứng dụng
này có thể đặt tiêu đề cho tài liệu đó trong tiêu đề Slug . Điều này làm cho quá trình tải lên trở
thành quy trình một bước thay vì quy trình hai bước (tải tệp lên bằng POST, sau đó chỉnh sửa siêu dữ
TE
Đây là một tiêu đề loại Chấp nhận khác , tiêu đề này cho phép khách hàng chỉ định mã hóa truyền nào sẽ
được chấp nhận (xem phần Mã hóa truyền để biết giải thích về mã hóa truyền). HTTP: Hướng dẫn dứt khoát
Giá trị của TE được gọi là “mã hóa chuyển giao” và IANA lưu giữ sổ đăng ký các mã hóa chuyển giao được
chấp nhận .
Khi máy chủ gửi phần thân thực thể bằng cách sử dụng mã hóa truyền theo khối, nó có thể chọn đặt một số
tiêu đề HTTP nhất định ở cuối phần thân thực thể thay vì trước nó (xem bên dưới để biết chi tiết). Điều
này biến chúng từ tiêu đề thành đoạn giới thiệu. Máy chủ báo hiệu rằng nó sẽ gửi tiêu đề dưới dạng đoạn
giới thiệu bằng cách đặt tên của nó làm giá trị của tiêu đề có tên là Đoạn giới thiệu. Đây là một giá
Máy chủ sẽ cung cấp giá trị cho Độ dài nội dung sau khi nó được phân phối phần nội dung thực thể và nó
hồi.
Mã hóa chuyển giao có cùng mục đích như Mã hóa nội dung: áp dụng một số biến
đổi tạm thời cho phần thân thực thể (thường là nén) sẽ được hoàn tác một cách
minh bạch ở đầu bên kia. Sự khác biệt là “đầu bên kia” có thể ở gần máy chủ
hơn với Mã hóa chuyển giao so với Mã hóa nội dung.
Hãy xem xét một thiết lập trong đó máy khách HTTP giao tiếp với máy chủ thông qua proxy.
Liên quan đến Mã hóa nội dung , hai đầu của cuộc trò chuyện là máy chủ và máy khách. Nhưng liên quan
đến Mã hóa chuyển giao , có hai cuộc trò chuyện xảy ra: một giữa máy khách và proxy và một giữa proxy
và máy chủ.
Nếu máy chủ nén phần thân thực thể và đặt Mã hóa nội dung: gzip, thì proxy sẽ (có thể) để nguyên phần
thân thực thể và chuyển nó, vẫn được nén, đến máy khách. Nhưng nếu máy chủ đặt Mã hóa truyền: gzip,
thì công việc của proxy là giải nén nội dung thực thể và chuyển nó, không bị nén, đến máy khách.
Giống như TE, giá trị của tiêu đề này được gọi là “mã hóa chuyển giao” và IANA lưu giữ sổ đăng ký các
xml. Hầu hết các mã hóa truyền đều đề cập đến các thuật toán nén và cũng có thể được sử dụng làm giá
trị cho Mã hóa nội dung, nhưng có một giá trị duy nhất cho Mã hóa truyền: chunked.
Đôi khi một máy chủ cần gửi một phần thân thực thể mà không biết các thông tin quan trọng như kích
thước của nó. Thay vì bỏ qua các tiêu đề HTTP như Content-Length và Content-MD5 dựa trên thông tin
này, máy chủ có thể quyết định gửi phần thân thực thể theo từng đoạn và đặt Content-Length và những
thứ tương tự sau phần thân thực thể thay vì trước đó.
Gửi Mã hóa Chuyển: "chunked" là cách máy chủ thông báo rằng nó sẽ thực hiện việc này. Vào thời điểm
tất cả các đoạn đã được gửi, máy chủ sẽ biết những điều mà nó không biết trước đó và nó có thể gửi
Content-Length và Content-MD5 dưới dạng “đoạn giới thiệu” thay vì “tiêu đề”.
Yêu cầu HTTP 1.1 là máy khách phải hỗ trợ mã hóa truyền theo khối, nhưng nhiều máy khách có thể lập
Loại nâng
Tầm quan trọng: Thấp, có khả năng cao trong tương lai.
Tiêu đề | 337
Machine Translated by Google
Nếu bạn muốn sử dụng một số giao thức khác ngoài HTTP, bạn có thể thông báo cho máy chủ biết điều đó
bằng cách gửi tiêu đề Nâng cấp . Nếu máy chủ tình cờ nói giao thức bạn muốn sử dụng, nó sẽ gửi lại mã
phản hồi 101 (Giao thức chuyển đổi) và ngay lập tức bắt đầu nói giao thức mới.
RFC 2817 thiết lập một sổ đăng ký IANA khác chứa các giá trị có thể có của tiêu đề Nâng cấp . Hiện tại
chỉ có ba giá trị trong sổ đăng ký: HTTP, TLS/1.0 (nghĩa là HTTPS) và WebSocket.
Ngoài WebSocket (một giao thức được xác định để sử dụng bởi trình duyệt web nhưng không phù hợp với mô
hình REST), tiêu đề Nâng cấp hiện không được sử dụng thường xuyên. Khách hàng muốn sử dụng HTTPS có thể
bắt đầu sử dụng HTTPS. Nhưng sẽ đến lúc tiêu chuẩn HTTP 2.0 được hoàn thiện, nhưng trước khi khách hàng
có thể cho rằng bất kỳ máy chủ cụ thể nào cũng hỗ trợ HTTP 2.0. Trong thời gian đó, tiêu đề Nâng cấp có
Tiêu đề này cho phép máy chủ biết loại phần mềm nào đang thực hiện yêu cầu HTTP.
Trên web của con người, đây là chuỗi xác định thương hiệu trình duyệt web. Trong thế giới API, nó thường
xác định thư viện HTTP hoặc thư viện ứng dụng khách được sử dụng để viết ứng dụng khách. Thay vào đó,
Ngay sau khi Web trở nên phổ biến, các máy chủ bắt đầu đánh hơi Tác nhân người dùng để xác định loại
trình duyệt ở đầu bên kia. Sau đó, họ gửi các bản trình bày khác nhau dựa trên giá trị của Tác nhân
người dùng. Đây là một ý tưởng khủng khiếp. Việc đánh hơi Tác nhân người dùng không chỉ gây ra sự không
tương thích giữa các trình duyệt web mà còn dẫn đến một cuộc chạy đua vũ trang bên trong chính tiêu đề
Hầu hết mọi trình duyệt ngày nay đều giả vờ là Mozilla, vì đó là tên mã nội bộ của trình duyệt web đầu
tiên trở nên phổ biến (Netscape Navigator). Một trình duyệt không giả vờ là Mozilla có thể không có được
sự thể hiện mà nó cần. Một số giả mạo cả Mozilla và Internet Explorer để có thể kích hoạt mã ban đầu
chỉ nhằm mục đích chạy trên Internet Explorer. Một số trình duyệt thậm chí còn cho phép người dùng chọn
Tác nhân người dùng cho mọi yêu cầu, để lừa máy chủ gửi các biểu diễn phù hợp. Đó là một mớ hỗn độn lớn.
Đừng để lịch sử lặp lại. API chỉ nên sử dụng Tác nhân người dùng để thu thập số liệu thống kê và từ chối quyền
truy cập vào các ứng dụng khách được lập trình kém. Nó không nên sử dụng Tác nhân người dùng để điều chỉnh các
biểu diễn của nó cho phù hợp với các khách hàng cụ thể. Điều tương tự cũng xảy ra với các cách khác để xác định
một tác nhân phần mềm cụ thể, chẳng hạn như thông tin xác thực ứng dụng khách OAuth.
Loại
Tiêu đề Vary cho khách hàng biết tiêu đề yêu cầu nào có thể thay đổi để nhận được các biểu diễn khác nhau
Giá trị đó cho khách hàng biết rằng nó có thể yêu cầu biểu diễn ở định dạng dữ liệu khác bằng cách đặt
hoặc thay đổi tiêu đề Chấp nhận . Nó có thể yêu cầu trình bày bằng một ngôn ngữ khác bằng cách đặt hoặc
Giá trị đó cũng yêu cầu bộ đệm lưu vào bộ nhớ đệm (giả sử) cách trình bày tài nguyên bằng tiếng Nhật tách
biệt với cách trình bày bằng tiếng Anh, ngay cả khi hai cách trình bày này có cùng một URL. Phiên bản
tiếng Nhật không phải là luồng byte hoàn toàn mới làm mất hiệu lực phiên bản tiếng Anh được lưu trong bộ
nhớ đệm. Hai yêu cầu đã gửi các giá trị khác nhau cho tiêu đề khác nhau (Ngôn ngữ chấp nhận), do đó, các
Nếu giá trị của Vary là *, điều đó có nghĩa là phản hồi hoàn toàn không được lưu vào bộ đệm.
Thông qua
Khi một yêu cầu HTTP đi trực tiếp từ máy khách đến máy chủ hoặc một phản hồi đi trực tiếp từ máy chủ đến
máy khách thì sẽ không có tiêu đề Via . Khi có các bên trung gian (chẳng hạn như proxy), mỗi bên sẽ đánh
vào tiêu đề Via trên thông báo yêu cầu hoặc phản hồi. Người nhận tin nhắn có thể nhìn vào tiêu đề Via để
biết đường dẫn mà tin nhắn HTTP đã đi qua các bên trung gian.
Loại cảnh
báo : Tiêu đề phản hồi (về mặt kỹ thuật có thể được sử dụng với các yêu cầu).
Tiêu đề Cảnh báo là phần bổ sung cho mã phản hồi HTTP. Nó thường được chèn bởi một trung gian như proxy
bộ nhớ đệm, để thông báo cho người dùng về các vấn đề có thể xảy ra mà không rõ ràng khi xem phản hồi.
Giống như mã phản hồi, mỗi cảnh báo HTTP có giá trị số gồm ba chữ số: “mã cảnh báo”. Hầu hết các cảnh
báo đều liên quan đến hành vi của bộ đệm. Cảnh báo này cho biết proxy bộ nhớ đệm tại localhost:9090 đã
gửi phản hồi được lưu trong bộ nhớ đệm mặc dù nó biết phản hồi đã cũ:
Tiêu đề | 339
Machine Translated by Google
Mã cảnh báo 110 có nghĩa là “Phản hồi đã cũ” cũng như mã phản hồi HTTP 404 có nghĩa là
“Không tìm thấy”. Tiêu chuẩn HTTP xác định bảy mã cảnh báo mà tôi sẽ không đề cập ở đây.
WWW-Xác thực
Loại: Tiêu đề phản hồi.
Tiêu đề này đi kèm với mã phản hồi 401 (Không được phép). Máy chủ yêu cầu máy khách gửi
một số xác thực vào lần tiếp theo khi nó yêu cầu URI. Nó cũng cho khách hàng biết loại
xác thực mà máy chủ mong đợi. Đây có thể sẽ là HTTP Basic Auth hoặc một số phiên bản
OAuth.
PHỤ LỤC C
Trong suốt cuốn sách này, tôi sử dụng thuật ngữ “Ràng buộc trường” như một cách viết tắt mang
tính khái niệm cho các nguyên tắc mà hệ thống RESTful phải tuân theo. Tôi nói về “tình trạng
không quốc tịch”, “hạn chế về siêu phương tiện”, v.v. Phụ lục này là nỗ lực của tôi nhằm giải
thích một cách trang trọng hơn một chút ý nghĩa của những thuật ngữ này và cách chúng tương tác với nhau.
Các ràng buộc Fielding là “thuộc tính kiến trúc” của Web được định nghĩa trong luận án Tiến sĩ
của Roy Fielding.1 Đây là một công việc khó hiểu đối với một nhà phát triển trung bình, một phần
lý luận dày đặc được viết theo phong cách học thuật và vận hành ở cấp độ cao hơn. mức độ trừu
tượng hơn RFC chẳng hạn. Vì vậy, hãy để tôi bắt đầu bằng cách cho bạn thấy những lợi ích thiết
Roy Fielding đã dành phần lớn thời gian của thập niên 1990 để chính thức hóa phiên bản 1.0 của
giao thức HTTP (trong RFC 1945) và phát triển phiên bản 1.1 (trở thành RFC 2616 nổi tiếng). Web
vốn đã là một thành công lớn, nhưng chính sự thành công đó của nó đã bộc lộ những vấn đề về thiết
kế khiến nó không thể mở rộng hơn nữa đến mức chúng ta đang có ngày nay.
Luận án Fielding đưa ra một số thuộc tính mà các hệ thống giống như web có thể có, sau đó chọn
ra các thuộc tính giúp Web thành công. Sau đó, nó chọn các ràng buộc—ràng buộc Fielding—sẽ làm
cho hệ thống mạng chung trông giống như Web. Những ràng buộc này là REST: một định nghĩa kiến
trúc chính thức nắm bắt được bản chất của Web.
Thoạt nhìn, đây là suy nghĩ viển vông. Web thực sự không đến từ một định nghĩa kiến trúc. Nó
được ghép lại với nhau bởi các nhà vật lý và tin tặc. Không có lý do gì nó lại phù hợp với khuôn
khổ lý thuyết của một nhà khoa học máy tính. Và đoán xem:
1. Fielding, Roy Thomas. Phong cách kiến trúc và thiết kế kiến trúc phần mềm dựa trên mạng. Luận
án tiến sĩ, Đại học California, Irvine, 2000.
341
Machine Translated by Google
nó không vừa! Có rất nhiều sự mất kết nối giữa trang web lý tưởng hóa được mô tả bởi các ràng buộc
Fielding và trang web thực tế vào giữa những năm 1990. Định nghĩa ban đầu về “tài nguyên” quá tập trung
vào các tài liệu tĩnh. Tiện ích mở rộng "cookie" phổ biến cho HTTP (ban đầu được xác định trong RFC
2109) đã gây ra sự cố lớn. Máy chủ đôi khi nhận được các yêu cầu HTTP hợp lệ mà họ không thể tìm ra
cách xử lý.
Đây là nơi mà lý thuyết của Fielding đã được đền đáp. Sự mất kết nối giữa các ràng buộc Fielding và
Web ngoài đời thực không có nghĩa là mô hình của anh ấy là vô dụng. Những sự ngắt kết nối đó chỉ ra
vấn đề nằm ở đâu! Việc sửa chúng sẽ làm cho Web thực sự giống với web lý tưởng hóa được mô tả bởi REST:
HTTP 1.1 (RFC 2616) và tiêu chuẩn URI (RFC 2396) đã khắc phục hầu hết sự mất kết nối giữa lý thuyết và
thực hành. Web đã được sửa chữa, sử dụng các ràng buộc Fielding làm bản thiết kế. Các lỗi ngắt kết nối
không thể khắc phục được, chẳng hạn như cookie HTTP, vẫn gây ra sự cố cho đến ngày nay.
Tôi nghĩ ý tưởng đằng sau “REST” rất quan trọng vì các API web gần giống như Web vào giữa những năm
1990. Chúng tôi có một loạt các hệ thống được ghép lại với nhau được thiết kế nhằm mang lại hiệu quả
hơn là khả năng mở rộng và khả năng bảo trì lâu dài.
Các ràng buộc của Fielding chỉ đường đến một thế giới tốt đẹp hơn. So sánh các API web mà chúng ta có
với một bộ nguyên tắc lý tưởng hóa có thể cho chúng ta thấy những gì cần phải khắc phục.
Vì vậy chúng ta hãy xem xét các đặc tính kiến trúc của Web; điều mà các ràng buộc Fielding đang cố gắng
nắm bắt.
Tất cả các trích dẫn trong phụ lục này đều lấy từ luận án Fielding. Tôi cũng khuyên bạn nên đọc bài
đăng trên blog năm 2008 của Fielding, “API REST phải được định hướng siêu văn bản”.
thể có: hiệu suất, tính đơn giản, độ tin cậy, v.v. Tất cả chỉ là chuyện làm mẹ và làm bánh táo. Sẽ
không ai lên tiếng phản đối “sự đơn giản” hay “độ tin cậy”.
Trong Chương 4, Fielding đưa ra những lựa chọn khó khăn. Chương đó xác định bốn thuộc tính kiến trúc
chính của World Wide Web. Đây là những đặc tính đã làm nên thành công của web và Fielding sẵn sàng hy
Vì việc tham gia vào việc tạo ra và cấu trúc thông tin là tự nguyện nên cần có
rào cản gia nhập thấp để có thể áp dụng đầy đủ.
Web thành công vì nó dễ sử dụng. Học cách sử dụng FTP hoặc Telnet đòi hỏi phải ghi nhớ rất nhiều lệnh
phức tạp. Nhưng khi bạn khởi động trình duyệt web, bạn thấy văn bản mà con người có thể đọc được và
nằm rải rác trong văn bản, bạn thấy các liên kết đến các trang liền kề.
342 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
trang web. Mỗi liên kết bao gồm một ít ngữ cảnh, giúp bạn quyết định nên nhấp vào liên kết nào. Bạn
sẽ nhấp vào một liên kết và quá trình này sẽ lặp lại.
So với các hệ thống siêu văn bản trước web, việc thiết lập một trang web cũng rất dễ dàng. Bạn không
cần sử dụng chương trình soạn thảo đặc biệt để viết trang HTML; bạn có thể sử dụng trình soạn thảo
văn bản.
Mặc dù tính đơn giản giúp có thể triển khai triển khai ban đầu của hệ thống phân tán,
nhưng khả năng mở rộng cho phép chúng tôi tránh bị mắc kẹt mãi mãi với những hạn chế của
những gì đã được triển khai. Ngay cả khi có thể xây dựng một hệ thống phần mềm hoàn toàn
phù hợp với yêu cầu của người dùng, những yêu cầu đó sẽ thay đổi theo thời gian giống như
xã hội thay đổi theo thời gian. Một hệ thống muốn tồn tại lâu dài như Web phải được chuẩn
bị cho sự thay đổi.
Nếu không có khả năng mở rộng, hệ thống chỉ có thể được triển khai một lần. Miễn là người dùng hài
lòng (và lúc đầu họ sẽ hài lòng!), thì mọi thứ đều ổn. Khi yêu cầu của người dùng thay đổi, họ sẽ
Web đã mang lại sự hài lòng cho người dùng trong 20 năm qua. Các đế chế tỷ đô đã trỗi dậy rồi sụp đổ
và được thay thế bởi các đế chế mới, tất cả đều dựa trên bốn công nghệ giống nhau: HTTP, URI, HTML và
JavaScript.
Hypermedia phân tán cho phép thông tin trình bày và điều khiển được lưu trữ ở các địa điểm
từ xa.
Trong bất kỳ hệ thống máy khách-máy chủ nào, máy chủ có quyền đối với tập dữ liệu. Nó “được lưu trữ ở
những địa điểm xa xôi”. Máy khách có thể cố gắng thay đổi tập dữ liệu nhưng những thay đổi của nó
Nguyên tắc của siêu phương tiện phân tán đưa ra các hướng dẫn về những gì bạn có thể làm với dữ liệu
(“thông tin trình bày và kiểm soát”) và xử lý dữ liệu đó theo cách tương tự như chính dữ liệu đó. Máy
Máy chủ web sử dụng tài liệu HTML để truyền tải trạng thái tài nguyên, thông báo liên kết giữa các
tài nguyên (chuyển tiếp an toàn) và thông báo các cơ chế được phép sửa đổi trạng thái tài nguyên
(chuyển tiếp không an toàn). Máy khách đọc tất cả thông tin này từ các tài liệu hypermedia mà nó nhận
được từ máy chủ, những tài liệu này có thể thay đổi khi hệ thống thay đổi.
“Thông tin trình bày và kiểm soát” có thể đi đâu khác? Nó có thể được lập trình vào máy khách hoặc có
thể được giữ hoàn toàn bên ngoài hệ thống, dưới dạng tài liệu mà con người có thể đọc được. Đó là
cách hầu hết các API ngày nay thực hiện. Cả hai kỹ thuật này đều gây khó khăn cho việc thay đổi cách
thức hoạt động của máy chủ mà không làm hỏng máy khách. Và nếu bạn không thể thay đổi máy chủ, bạn
Quy mô Internet
“Quy mô Internet” nghe giống như một từ thông dụng có nghĩa là “thực sự lớn”, nhưng Fielding có
hai điều cụ thể trong đầu. Đầu tiên, “khả năng mở rộng vô chính phủ”, bác bỏ ý tưởng về mối quan
hệ lâu dài hoặc sự phối hợp giữa các bộ phận khác nhau của hệ thống.
Khách hàng không thể mong đợi duy trì kiến thức về tất cả các máy chủ. Không thể mong đợi
máy chủ lưu giữ được thông tin về trạng thái của các yêu cầu. Các phần tử dữ liệu Hypermedia
không thể giữ lại “con trỏ ngược”, một mã định danh cho từng phần tử dữ liệu tham chiếu
đến chúng, vì số lượng tham chiếu đến một tài nguyên tỷ lệ thuận với số lượng người quan
tâm đến thông tin đó.
Thứ hai, “triển khai độc lập”, nói rằng vì không có mối quan hệ lâu dài nên các phần khác nhau
Nhiều ranh giới tổ chức cũng có nghĩa là hệ thống phải được chuẩn bị cho sự thay đổi dần
dần và rời rạc, trong đó việc triển khai cũ và mới cùng tồn tại mà không ngăn cản việc
triển khai mới tận dụng các khả năng mở rộng của chúng…
Kiến trúc nói chung phải được thiết kế để dễ dàng triển khai các phần tử kiến trúc theo
kiểu từng phần, lặp đi lặp lại, vì không thể ép buộc triển khai theo cách có trật tự.
Đó là bốn thuộc tính kiến trúc quan trọng của Web, như Fielding thấy chúng. Rõ ràng là một số
thuộc tính này cũng áp dụng cho API web. Tất cả những điều khác đều bình đẳng, chúng tôi muốn
một hệ thống có thể mở rộng hơn một hệ thống không thể thay đổi theo thời gian. Ngay cả một API
nhỏ cũng có “quy mô Internet” nếu nó ở trên Internet công cộng, vì nó phải đối mặt với các vấn
đề đi kèm với khả năng mở rộng hỗn loạn và triển khai độc lập.
Nhưng sẽ là sai lầm khi cho rằng những nguyên tắc này có thể được chuyển trực tiếp sang thế giới
API web. Có một sự khác biệt lớn được xác định giữa Web và API web: khoảng cách ngữ nghĩa. Sự
khác biệt này làm mất ổn định mối quan hệ giữa các thuộc tính kiến trúc của Web và buộc chúng
ta phải lựa chọn giữa bốn thuộc tính mong muốn.
Khi con người đưa ra mọi quyết định, “siêu phương tiện phân tán” là cách dễ nhất để hạ thấp “rào
cản gia nhập”. Con người nhìn thấy tất cả các chuyển đổi trạng thái có thể xảy ra và được chọn
một trạng thái vào thời điểm đó. Nhưng nếu không có con người tham gia vào vòng đưa ra quyết
định, lập trình viên phải tạo ra một chương trình phần mềm có khả năng thay thế con người còn thiếu.
Trong tình huống đó, “siêu phương tiện phân tán” sẽ làm tăng “rào cản gia nhập”. Các tài liệu
Hypermedia chia một vấn đề riêng lẻ thành các phần nhỏ và việc tạo ra một robot đưa ra quyết
định đòi hỏi sự hiểu biết về toàn bộ không gian vấn đề.
Cách dễ nhất để hạ thấp “rào cản gia nhập” đối với API web là loại bỏ thuộc tính “siêu phương
tiện được phân phối” và mô tả trước một hệ thống bằng văn xuôi mà con người có thể đọc được.
344 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
Vấn đề với điều đó là, thuộc tính “siêu phương tiện phân tán” là thứ duy nhất giữ được thuộc tính “khả
năng mở rộng”. Việc thay đổi một số văn bản mà con người có thể đọc được sẽ không thay đổi chế độ xem hệ
thống của khách hàng cho phù hợp. Nếu không có “siêu phương tiện phân tán”, không có gì đảm bảo có thể
thay đổi cách nhìn của khách hàng về hệ thống. “Quy mô Internet” cho biết có quá nhiều khách hàng cần
theo dõi và những khách hàng chưa nâng cấp có thể tồn tại trong một thời gian dài.
Thay vào đó, khi những ứng dụng khách đó chứa thông tin được mã hóa cứng có thể được đưa vào “siêu phương
tiện phân tán”, bạn sẽ mất “khả năng mở rộng”. API của bạn ban đầu trông giống như câu trả lời cho những
lời cầu nguyện của người dùng, nhưng khi yêu cầu của họ thay đổi, chúng sẽ trôi đi và bạn không thể thay
Trên Web, bốn nguyên tắc kiến trúc củng cố lẫn nhau. Trong thế giới API web, chúng đang rất căng thẳng.
• Nếu bạn có cách nào đó buộc tất cả khách hàng của mình phải nâng cấp theo từng bước, bạn có thể từ
bỏ “quy mô Internet”. Sau đó, bạn có thể có “rào cản gia nhập thấp” và “khả năng mở rộng” mà không
cần sử dụng “siêu phương tiện phân tán”. Đây là lựa chọn phổ biến cho API được triển khai trong công
ty.
• Nếu bạn cần “quy mô Internet”, bạn có thể từ bỏ “khả năng mở rộng” và “siêu phương tiện phân tán” vì
lợi ích của “rào cản gia nhập thấp”. Hầu hết các API web công cộng ngày nay đều thực hiện việc này.
• Hoặc bạn có thể nắm lấy “siêu phương tiện phân tán” và có được “khả năng mở rộng” và “quy mô
Internet” với chi phí là “rào cản gia nhập” cao hơn. Đó là cách tiếp cận tôi thực hiện trong cuốn sách này.
Công việc của tôi trên ALPS và trên các cấu hình nói chung là một nỗ lực nhằm hạ thấp “rào cản gia
Bây giờ chúng ta hãy xem xét các ràng buộc Fielding, các quy tắc mang lại cho World Wide Web những đặc
tính kiến trúc mong muốn. Bốn ràng buộc Fielding nổi tiếng nhất được tìm thấy trong một nhận xét duy nhất
REST được xác định bởi bốn ràng buộc giao diện: xác định tài nguyên; thao túng tài nguyên
thông qua các biểu diễn; tin nhắn tự mô tả; và hypermedia là động cơ của trạng thái ứng
dụng. Những hạn chế này sẽ được thảo luận trong Phần 5.2.
Những ràng buộc này tạo nên “giao diện thống nhất” của REST. Chúng thực sự được thảo luận ở Phần 5.2,
nhưng không ở dạng danh sách thuận tiện mà bạn có thể mong đợi. Trong phần này, tôi sẽ thảo luận chúng
yêu cầu về quy mô và miền đa tổ chức của Web, thay vào đó, REST dựa vào việc tác giả chọn
một mã định danh tài nguyên phù hợp nhất với bản chất của khái niệm được xác định.
“Xác định tài nguyên” là tên của Fielding cho cái mà tôi gọi là “khả năng xác định địa chỉ”.
URI xác định một tài nguyên. Trạng thái của tài nguyên có thể thay đổi nhưng URI của nó vẫn
giữ nguyên. Nếu URI của tài nguyên thay đổi, máy chủ sẽ sử dụng hypermedia ( tiêu đề Vị trí )
để hướng máy khách đến URI mới.
Ngày nay Web chiếm ưu thế đến mức thật khó để tưởng tượng những “hệ thống siêu văn bản truyền
thống” luôn thay đổi định danh của chúng. Nhưng không khó để tưởng tượng ra một vấn đề khác:
các trang web và API gán quá nhiều trạng thái tài nguyên cho một URL, giống như các trang web
nhà hàng mà tôi đã phàn nàn trong Chương 1.
Web có cái nhìn mở rộng về khái niệm “tài nguyên”. Một nguồn tài nguyên có thể là bất cứ thứ
gì. Điều này có nghĩa là có những tài nguyên—các đối tượng vật lý và các khái niệm trừu tượng—
không thể gửi qua Internet. Tuy nhiên, chúng ta có thể nói về những tài nguyên này bằng cách
sử dụng các biểu diễn.
Biểu diễn là một “chuỗi byte”, vì vậy nó có thể được truyền qua mạng. Nó “nắm bắt [các] trạng
thái hiện tại hoặc dự định của tài nguyên”, vì vậy khách hàng có thể sử dụng nó làm vật thay
thế cho tài nguyên thực. Và một biểu diễn không bị ràng buộc với mã phía máy chủ đã tạo ra nó,
điều đó có nghĩa là nó không phải thay đổi khi việc triển khai máy chủ thay đổi.
Trên Web, máy khách và máy chủ thao tác tài nguyên bằng cách gửi biểu diễn qua lại bằng cách
sử dụng một tập hợp nhỏ các phương thức HTTP được tiêu chuẩn hóa (GET và POST). API web có thể
thêm một vài phương thức nữa (PUT, DELETE, v.v.), nhưng đây vẫn là một tập hợp nhỏ cần có sự
đồng thuận của cộng đồng để mở rộng. Sự phong phú của các tương tác giữa máy khách và máy chủ
gần như hoàn toàn được tìm thấy trong các biểu diễn mà chúng gửi cho nhau.
Tin nhắn tự mô tả
REST cho phép xử lý trung gian bằng cách hạn chế các thông báo tự mô tả: tương tác không
có trạng thái giữa các yêu cầu, các phương thức tiêu chuẩn và loại phương tiện được sử
dụng để biểu thị ngữ nghĩa và trao đổi thông tin, còn các phản hồi biểu thị rõ ràng khả
năng lưu trữ.
Một thông điệp HTTP chứa tất cả thông tin cần thiết để người nhận hiểu được nó. Không có tài
liệu trôi nổi tự do nào gần đó mà khách hàng cũng phải hiểu. Nếu việc hiểu một thông điệp đòi
hỏi phải hiểu một số tài liệu khác
346 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
giống như định nghĩa loại phương tiện hoặc cấu hình, thì thông báo phải chứa tham chiếu đến tài liệu
1. “Tương tác giữa các yêu cầu là không trạng thái.” Ràng buộc không trạng thái (được đề cập bên
dưới) chỉ là một trường hợp đặc biệt của ràng buộc thông điệp tự mô tả. Trong hệ thống không
trạng thái, máy chủ có thể xử lý yêu cầu của khách hàng mà không cần phải nhớ cách nó xử lý tất
cả các yêu cầu trước đó của khách hàng đó. Mỗi yêu cầu đứng một mình.
2. “Các phương pháp và loại phương tiện tiêu chuẩn được sử dụng để biểu thị ngữ nghĩa và trao đổi
thông tin.” Khá đơn giản. Nếu phản hồi HTTP không bao gồm tiêu đề Kiểu nội dung thì máy khách
sẽ không biết cách phân tích nội dung thực thể. Nếu một yêu cầu HTTP không đề cập đến phương
thức HTTP sẽ sử dụng hoặc tạo ra các phương thức riêng của nó thì máy chủ sẽ không biết cách xử
lý nó.
3. “Phản hồi cho biết rõ ràng khả năng lưu vào bộ nhớ đệm.” Một khách hàng vừa nhận được phản hồi
HTTP từ máy chủ web. Việc khách hàng lưu vào bộ nhớ đệm phản hồi có hợp lý không? Nếu có thì
trong bao lâu? Trong một phút, hay trong một năm?
Khách hàng không cần phải đưa ra quyết định này. Máy chủ ở vị trí tốt hơn nhiều để biết phản
hồi có thể được lưu vào bộ nhớ đệm an toàn trong bao lâu. Vì vậy, nhiệm vụ của máy chủ là cung
Bây giờ, đây là nơi xuất hiện các thông báo tự mô tả. Trong HTTP, máy chủ truyền tải thông tin
bộ nhớ đệm bằng cách thêm tiêu đề vào chính phản hồi HTTP có thể được lưu vào bộ nhớ đệm. Không
có giao tiếp ngoài băng tần nào mà máy chủ giải thích cách lưu vào bộ nhớ đệm tin nhắn vừa gửi.
Hướng dẫn lưu vào bộ nhớ đệm là một phần của tin nhắn và chúng được lưu vào bộ nhớ đệm cùng với
tin nhắn. Khi đến lúc truy xuất tin nhắn từ bộ đệm và kiểm tra xem nó có còn mới hay không,
khách hàng có thể đưa ra quyết định dựa trên thông tin có trong tin nhắn.
Các phiên bản trước của HTTP không còn phù hợp với “thông điệp tự mô tả” lý tưởng. Phần 6.3.2 của
Fielding thảo luận về một số vấn đề mà điều này gây ra. Đáng chú ý nhất là nếu không có tiêu đề Máy
chủ , máy chủ sẽ không có cách nào để biết tên miền nào sẽ xử lý yêu cầu HTTP đến. Điều này gây khó
khăn cho việc lưu trữ nhiều tên miền trên một
máy chủ.
Ngay cả trong HTTP 1.1, thông báo phản hồi cũng không chứa bất kỳ thông tin nào liên quan đến yêu
cầu ban đầu. Đây là sự thất bại trong việc đáp ứng ràng buộc về thông điệp tự mô tả.
So sánh điều này với giao thức CoAP, giao thức này liên kết các phản hồi với các yêu cầu sử dụng mã
thông báo và ID tin nhắn. HTTP 2.0 có thể sẽ làm điều gì đó tương tự.
Luận án Fielding chưa bao giờ định nghĩa rõ ràng cụm từ khét tiếng “hypermedia là động cơ của trạng thái
ứng dụng”, nhưng nếu bạn hiểu các khái niệm riêng lẻ thì nó sẽ có ý nghĩa:
1. Tất cả trạng thái ứng dụng được lưu giữ ở phía máy khách. Những thay đổi về trạng thái ứng dụng là
2. Máy khách chỉ có thể thay đổi trạng thái ứng dụng của mình bằng cách thực hiện yêu cầu HTTP và xử lý
phản hồi.
3. Làm thế nào để khách hàng biết họ có thể thực hiện yêu cầu nào tiếp theo? Bằng cách xem xét các điều
khiển siêu phương tiện trong các biểu diễn mà nó nhận được cho đến nay.
4. Do đó, điều khiển hypermedia là động lực đằng sau những thay đổi trong ứng dụng
tình trạng.
Ràng buộc hypermedia không phải là việc vặt mà bạn phải thực hiện để “YÊU CẦU”. Đó là phần thưởng cho việc
tuân theo các ràng buộc khác. Nó cung cấp cho bạn khả năng mở rộng. Ràng buộc hypermedia cho phép máy khách
thông minh tự động thích ứng với những thay đổi ở phía máy chủ. Nó cho phép máy chủ thay đổi cách triển khai
cơ bản mà không làm hỏng tất cả các máy khách của nó.
Hypermedia được chọn làm giao diện người dùng vì tính đơn giản và tổng quát của nó: cùng một
giao diện có thể được sử dụng bất kể nguồn thông tin nào, tính linh hoạt của các mối quan hệ
siêu phương tiện (các liên kết) cho phép cấu trúc không giới hạn và việc thao tác trực tiếp các
liên kết cho phép thực hiện các thao tác phức tạp. các mối quan hệ trong thông tin để hướng dẫn
người đọc thông qua một ứng dụng.
Chương 3 của Fielding sử dụng rất nhiều kiến trúc mạng có thể có khác nhau và phân tách chúng thành “các
thuộc tính kiến trúc”: các ràng buộc nguyên tử, có thể hoán đổi cho nhau trên một “kiểu rỗng” chung. Chương
3 cho thấy những ràng buộc cơ bản này có thể được kết hợp để mô tả các kiến trúc chung như hệ thống đối
Chương 5 nổi tiếng của Fielding, “Chuyển giao trạng thái đại diện”, áp dụng cách tiếp cận giải cấu trúc này
cho World Wide Web. Hóa ra Web bao gồm năm thuộc tính từ Chương 3 của Fielding (“Máy khách-Máy chủ”, “Không
trạng thái”, “Bộ đệm”, “Hệ thống phân lớp” và “Mã theo yêu cầu”). Ngoài ra còn có thuộc tính thứ sáu (“Giao
diện đồng nhất”), được tạo thành từ bốn ràng buộc về giao diện mà tôi đã đề cập trước đó. Ràng buộc về giao
diện thống nhất bao gồm hầu hết những điều tạo nên sự độc đáo của Web.
Nói chung, các API web quan tâm rất nhiều đến “Máy khách-Máy chủ”, “Không trạng thái”, “Bộ nhớ đệm” và “Giao
diện thống nhất”. “Hệ thống phân lớp” quan trọng đối với việc triển khai API web hơn là
348 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
thiết kế của họ. API Web hoàn toàn không sử dụng “Mã theo yêu cầu”. Như vậy, đây là cái nhìn
chi tiết về tất cả các hạn chế về kiến trúc của Web.
Một thành phần máy khách mong muốn một dịch vụ được thực hiện sẽ gửi yêu cầu đến máy chủ thông qua một
trình kết nối. Máy chủ từ chối hoặc thực hiện yêu cầu và gửi phản hồi lại cho máy khách.
Điều này hẳn là quen thuộc vì máy khách-máy chủ là kiến trúc mạng thống trị trên Internet. Nó
xuất hiện ngay cả ở những nơi mà bạn có thể không ngờ tới. Nhiều kiến trúc ngang hàng là kiến
trúc máy khách-máy chủ; chỉ là một thiết bị ngang hàng nhất định đôi khi hoạt động như một “máy
khách” và đôi khi là “máy chủ”.
Đối thủ chính của kiến trúc client-server là kiến trúc tích hợp dựa trên sự kiện, trong đó các
thành phần liên tục phát các sự kiện qua mạng, đồng thời lắng nghe các sự kiện mà chúng quan
tâm. Không có giao tiếp một-một giữa các bộ phận của hệ thống , trong đó một bên có thể được coi
là “khách hàng” và một bên khác là “máy chủ”. Chỉ có phát sóng và nghe lén.
Mục tiêu là cải thiện khả năng mở rộng của máy chủ bằng cách loại bỏ mọi nhu cầu đối với máy chủ để duy
trì nhận thức về trạng thái máy khách ngoài yêu cầu hiện tại.
Đối với máy chủ HTTP, khi máy khách hiện không đưa ra yêu cầu, máy khách đó không tồn tại. Tất
cả trạng thái ứng dụng—thông tin về đường dẫn của một máy khách cụ thể thông qua ứng dụng—thuộc
Nếu một phần trạng thái ứng dụng nào đó quan trọng đến mức máy chủ cần quan tâm thì nó sẽ trở
thành trạng thái tài nguyên. Nó phải được tạo thành một tài nguyên, có URL riêng. Bằng cách đó,
máy chủ có quyền kiểm soát trạng thái, nhưng máy khách có thể thao tác nó theo cách nó thao tác
các tài nguyên khác.
Đặc biệt, điều này có nghĩa là bạn không nên lưu trữ ID phiên trên máy chủ. Để trích dẫn Field-
ing:
Một hình thức lạm dụng là bao gồm thông tin xác định người dùng hiện tại trong tất cả URI được tham
chiếu bởi biểu diễn phản hồi hypermedia. Các id người dùng được nhúng như vậy có thể được sử dụng để
duy trì trạng thái phiên trên máy chủ, theo dõi hành vi của người dùng bằng cách ghi nhật ký hành động
của họ hoặc thực hiện tùy chọn của người dùng trên nhiều hành động… bằng cách vi phạm các ràng buộc của
REST, các hệ thống này cũng khiến bộ nhớ đệm dùng chung trở nên không hiệu quả, giảm khả năng mở rộng
của máy chủ và dẫn đến những tác động không mong muốn khi người dùng chia sẻ những tài liệu tham khảo
đó với người khác.
Bộ nhớ đệm
Hình thức sao chép này thường được tìm thấy nhiều nhất trong trường hợp tập dữ liệu tiềm năng
vượt xa khả năng của bất kỳ khách hàng nào, như trong WWW[.]
Nhờ ràng buộc thông điệp tự mô tả, tất cả thông tin cần thiết để hiểu một phản hồi đều được chứa
trong chính phản hồi đó. Nhờ hạn chế không trạng thái, một yêu cầu HTTP có thể được xem xét riêng
lẻ, độc lập với bất kỳ yêu cầu nào khác. Hai hạn chế này làm cho bộ nhớ đệm có thể thực hiện được.
Máy khách HTTP có thể tự động khớp các yêu cầu của nó với các phản hồi trước đó mà nó nhận được, có
thể tiết kiệm một chuyến đi khứ hồi qua mạng. Như Fielding nói, “hiệu suất ứng dụng tốt nhất sẽ đạt
Việc triển khai được tách rời khỏi các dịch vụ mà chúng cung cấp, điều này khuyến khích khả
năng phát triển độc lập. Tuy nhiên, sự đánh đổi là giao diện thống nhất sẽ làm giảm hiệu quả
vì thông tin được truyền ở dạng chuẩn hóa thay vì dạng dành riêng cho nhu cầu của ứng dụng.
Giao diện REST được thiết kế để mang lại hiệu quả cho việc truyền dữ liệu siêu phương tiện
quy mô lớn, tối ưu hóa cho trường hợp phổ biến của Web nhưng dẫn đến giao diện không tối ưu
cho các hình thức tương tác kiến trúc khác.
Tôi đã bao gồm giao diện thống nhất. Nó được tạo thành từ bốn ràng buộc giao diện mà tôi đã đề cập
trước đó: khả năng đánh địa chỉ, thao tác tài nguyên thông qua các biểu diễn, thông báo tự mô tả và
Fielding chỉ ra rằng những hạn chế này thiên về “truyền dữ liệu siêu phương tiện quy mô lớn”. Một
trình duyệt Web thông thường bắt đầu ngày mới bằng cách gửi yêu cầu GET tới một URL (khả năng xác
định địa chỉ) và truy xuất một bản trình bày HTML lớn chứa đầy các liên kết (sử dụng các bản trình
bày). Người dùng của nó đọc tài liệu và theo dõi một trong các liên kết (ràng buộc siêu phương
tiện). Điều này làm cho trình duyệt gửi một yêu cầu GET khác và truy xuất một biểu diễn HTML khác
Phần lớn các yêu cầu HTTP là các yêu cầu GET thực hiện chuyển đổi trạng thái an toàn.
Đây là lý do tại sao rất nhiều biện pháp tối ưu hóa hiệu suất của HTTP—bộ nhớ đệm, yêu cầu có điều
kiện, yêu cầu một phần—tập trung vào việc giảm chi phí của các yêu cầu GET.
Nếu các thiết kế API tập trung chủ yếu vào việc chuyển đổi trạng thái không an toàn thì sẽ có sự mất
kết nối lớn giữa giao diện thống nhất của Web và giao diện đáp ứng tốt nhất nhu cầu của khách hàng
API. Nhưng hóa ra các máy khách API cũng dành phần lớn thời gian của họ để thực hiện việc truyền dữ
liệu ở quy mô lớn (nếu không phải là truyền siêu phương tiện). Đó là lý do tại sao cái gọi là “RESTful”
API có thể rất thành công ngay cả khi không tuân theo ràng buộc về hypermedia. Nó mang lại cho người
dùng lợi ích của ba ràng buộc giao diện khác.
Một số API nhận biết siêu phương tiện bỏ qua phần “chi tiết lớn” của “truyền siêu phương tiện chi
tiết lớn”. Thay vì phục vụ một tài liệu lớn truyền tải nhiều trạng thái tài nguyên (chẳng hạn như
tài liệu hCard mô tả một người), họ chia thông tin thành nhiều phần.
350 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
tài nguyên (cung cấp các URL riêng cho tên, họ và ngày sinh của người đó). Máy khách phải thực hiện
một số yêu cầu GET để có được thông tin cần thiết. Kết quả là một API “trò chuyện” có độ trễ rất cao.
Điều này không sai về mặt kỹ thuật nhưng lại ảnh hưởng xấu đến hiệu suất. HTTP 2.0 sẽ giúp việc viết
loại API này trở nên thiết thực hơn: một loại dựa trên việc truyền siêu phương tiện ở mức độ nhỏ .
Layered-client-server thêm các thành phần proxy và cổng vào kiểu client-server…
Các thành phần trung gian bổ sung này có thể được thêm vào nhiều lớp để thêm các tính
năng như cân bằng tải và kiểm tra bảo mật cho hệ thống.
Xuyên suốt cuốn sách này, tôi nói về các máy khách HTTP—các phần mềm tạo ra các yêu cầu HTTP—và các
máy chủ HTTP—các phần mềm tạo ra các phản hồi HTTP. Nhưng thông số kỹ thuật HTTP xác định hai phần mềm
khác có thể đi giữa máy khách và máy chủ: proxy và cổng. Tất cả những thứ này đều là thành phần trong
hệ thống HTTP.
Proxy nhận yêu cầu HTTP từ các thành phần (máy khách, proxy và cổng), giống như máy chủ web. Không
giống như máy chủ web, proxy không tự xử lý yêu cầu. Thay vào đó, nó chuyển yêu cầu đến một thành phần
khác (máy chủ, proxy hoặc cổng) và chờ phản hồi. Khi nhận được phản hồi, proxy sẽ chuyển nó trở lại
thành phần đã gửi yêu cầu. Proxy có thể sửa đổi các yêu cầu và phản hồi trong quá trình chuyển tiếp;
để nén dữ liệu, loại bỏ thông tin nhận dạng hoặc thực hiện kiểm duyệt.
Cổng là một proxy dịch giữa HTTP và một số giao thức khác. Một cổng có thể nhận một yêu cầu HTTP, biến
nó thành một chuỗi lệnh để tải xuống tệp từ máy chủ FTP, sau đó phân phát tệp đã tải xuống dưới dạng
nội dung thực thể của phản hồi HTTP. Đối với khách hàng, nó thực hiện các yêu cầu HTTP thông thường
Ràng buộc “hệ thống phân lớp” ít liên quan đến proxy và cổng hơn, mà liên quan nhiều hơn đến thực tế
là việc thêm một proxy giữa máy khách và máy chủ là một hoạt động gần như minh bạch. Máy khách không
biết liệu nó đang nói chuyện trực tiếp với máy chủ hay đang nói chuyện với proxy nói chuyện với proxy
Máy khách, máy chủ, proxy và cổng đều có cùng giao diện. Không có “giao thức proxy” đặc biệt nào cả.
Proxy nhận yêu cầu HTTP và gửi phản hồi HTTP. Có một số mã trạng thái đặc biệt liên quan đến proxy
(tôi đề cập ở Phụ lục A); một số tiêu đề HTTP để kiểm soát proxy (Phụ lục B); và hai phương thức HTTP,
CONNECT và TRACE, để sử dụng và gỡ lỗi proxy. Nhưng đối với khách hàng, proxy trông giống như máy chủ
HTTP. Đối với máy chủ, proxy trông giống như máy khách HTTP.
HTTP xác định rất nhiều quy tắc phức tạp về cách phần tử kiến trúc “hệ thống phân lớp” tương tác với
phần tử “bộ nhớ đệm”, nhưng kịch tính đó diễn ra hoàn toàn trong một thành phần proxy. Khách hàng và
Proxy rất hữu ích trong việc triển khai API trong thế giới thực. Một proxy có thể thực hiện cân bằng tải
bằng cách gửi các yêu cầu khác nhau đến các máy chủ khác nhau. Một proxy có thể lưu vào bộ nhớ đệm các
biểu diễn được truy cập thường xuyên để các yêu cầu của máy khách không phải lúc nào cũng được gửi đến máy chủ.
Nhưng tôi không đề cập đến proxy và cổng trong cuốn sách này vì toàn bộ tiền đề của hệ thống phân lớp là
chúng vô hình. Các ràng buộc Fielding khác, đặc biệt là trạng thái không trạng thái, giúp có thể thêm và
xóa các chuỗi trung gian khổng lồ giữa máy khách và máy chủ mà không cần máy khách hoặc máy chủ nhận ra.
Để biết cách xử lý chi tiết về proxy và cổng, tôi khuyên bạn nên xem Chương 6 và 8 của HTTP: Hướng dẫn dứt
khoát.
Thành phần máy khách [A] có quyền truy cập vào một tập hợp tài nguyên nhưng không có
bí quyết về cách xử lý chúng. Nó gửi yêu cầu đến một máy chủ từ xa để lấy mã đại diện
cho bí quyết đó, nhận mã đó và thực thi nó cục bộ…. [T]hạn chế đáng kể nhất là thiếu
khả năng hiển thị do máy chủ gửi mã thay vì dữ liệu đơn giản. Thiếu khả năng hiển thị
dẫn đến các vấn đề triển khai rõ ràng nếu máy khách không thể tin cậy vào máy chủ.
Mã theo yêu cầu dành cho phần mềm giống như hypermedia làm với dữ liệu. World Wide Web hoạt động theo mã
theo yêu cầu, nhưng tôi không đề cập đến nó trong cuốn sách này, vì tôi không có lời khuyên hữu ích nào
cho việc sử dụng nó trong ngữ cảnh của một API web. Trong số hàng tá định dạng hypermedia mà tôi đã đề
cập, định dạng duy nhất hỗ trợ mã theo yêu cầu là HTML.
Bí mật của HTML là thẻ <script> , thẻ này tự động tìm nạp phần trình bày của một tài nguyên và sau đó thực
thi phần trình bày đó dưới dạng mã (JavaScript). Nhờ thẻ <script> , người dùng truy cập trang web của bạn
có thể tải xuống và chạy một ứng dụng phần mềm phức tạp. Khi ứng dụng thay đổi, người dùng sẽ “cài đặt
lại” mã bằng cách tải lại trang web và tải lại mọi thứ.
Chiến lược triển khai chủ yếu cho mã máy khách API là viết thư viện bằng nhiều ngôn ngữ lập trình khác
nhau (API cho API, nếu bạn muốn) và cung cấp chúng để các nhà phát triển cá nhân tải xuống. Đây là một ý
tưởng tồi, vì lý do tương tự, các API thiếu hiểu biết về siêu phương tiện cũng là một ý tưởng tồi. Nó phá
hủy khả năng mở rộng. Cuối cùng, máy khách sẽ thay đổi nhưng không ai thông báo cho cơ sở đã cài đặt hiện
có. Phiên bản cũ của máy khách khởi động và chạy cùng một đoạn mã mà nó luôn chạy, nhưng giờ đây lại là
mã sai.
Mã theo yêu cầu có thể giải quyết vấn đề này. Với mã theo yêu cầu, thư viện khách hàng có thể tải xuống
các phiên bản mới của chính chúng khi chúng được phát hành. Miễn là API ngôn ngữ lập trình của máy khách
vẫn giữ nguyên, mã dựa trên thư viện máy khách sẽ tiếp tục hoạt động khi cách triển khai cơ bản thay đổi.
Vấn đề là không ai thực sự thích ý tưởng tự động tải xuống và chạy mã từ máy chủ của người khác. Nếu một
máy chủ phục vụ các tài liệu hypermedia bị xâm phạm, các máy khách của nó có thể nhận được dữ liệu không
có thật. Điều đó thật tệ, nhưng nó có thể còn tệ hơn rất nhiều. Nếu một
352 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
máy chủ phục vụ mã theo yêu cầu bị xâm phạm, các máy khách của nó cũng có thể bị xâm phạm!
Mã theo yêu cầu hoạt động trên Web vì trình duyệt web chạy mã JavaScript đã tải xuống trong hộp cát. Mặc
dù vậy, mã theo yêu cầu vẫn dẫn đến các vấn đề bảo mật trình duyệt như tấn công kịch bản chéo trang. Máy
Họ cần quyền truy cập vào hệ thống tệp cục bộ, cơ sở dữ liệu và các tài nguyên hệ thống khác. Mã theo
yêu cầu không tốt có thể gây ra nhiều thiệt hại cho hệ thống.
Trong môi trường mà tất cả các bên tin tưởng lẫn nhau (chẳng hạn như trong một công ty), việc triển khai
bằng cách sử dụng mã theo yêu cầu có thể hợp lý. Nhưng đó là môi trường mà kiến trúc RESTful yếu nhất và
có nhiều cách khác được thiết lập tốt để máy chủ đáng tin cậy triển khai phần mềm cho máy khách.
Vì tất cả những lý do này, tôi không mong đợi mã theo yêu cầu sẽ sớm thay thế các ứng dụng khách có thể
tải xuống. Ứng dụng khách có thể tải xuống cho API nhận biết hypermedia ít có khả năng bị hỏng hơn khi
API thay đổi, khiến nó có thể tồn tại mà không cần mã theo yêu cầu.
Thành công của Web đến từ bốn đặc tính kiến trúc sau: Rào cản gia nhập thấp Thật
Khả năng mở
rộng Các trang web riêng lẻ có thể thay đổi qua đêm mà không ảnh hưởng đến khách hàng của họ. Trong
suốt nhiều thập kỷ, toàn bộ Web đã thay đổi đáng kể, nhưng các công nghệ cơ bản không thay đổi nhiều
lắm.
tin về những gì khách hàng có thể làm với dữ liệu của máy chủ được lưu giữ ở cùng một nơi với dữ
liệu và được gửi đến khách hàng trong cùng một tài liệu.
quy mô Internet
Không có mối quan hệ lâu dài giữa các bộ phận của hệ thống và các bộ phận khác nhau có thể thay đổi
Những thuộc tính kiến trúc này được hiện thực hóa trên Web bởi sáu ràng buộc kiến trúc:
Không
trạng thái Khi một máy khách hiện không đưa ra yêu cầu, máy chủ không biết nó tồn tại.
Bộ đệm
Máy khách có thể lưu các chuyến đi qua mạng bằng cách sử dụng lại các phản hồi trước đó từ bộ đệm.
Các trung gian như proxy có thể được chèn vô hình giữa máy khách và máy chủ.
Máy chủ có thể gửi mã thực thi ngoài dữ liệu. Mã này được triển khai tự động khi khách hàng yêu
Thao tác tài nguyên thông qua các biểu diễn Máy chủ mô tả
trạng thái tài nguyên bằng cách gửi các biểu diễn đến máy khách. Máy khách thao tác trạng thái
tài nguyên bằng cách gửi các biểu diễn đến máy chủ.
thông tin cần thiết để hiểu một tin nhắn yêu cầu hoặc phản hồi đều được chứa trong (hoặc ít nhất
Máy chủ điều khiển trạng thái của máy khách bằng cách gửi một “menu” hypermedia chứa các tùy chọn
Chín (hoặc mười, tùy thuộc vào cách bạn đếm) ràng buộc này là các ràng buộc Fielding.
Nếu khoảng cách ngữ nghĩa không tồn tại, việc thiết kế API web sẽ giống hệt như thiết kế một trang
web. Chúng ta có thể sao chép Web một cách mù quáng mà không thực sự hiểu nó hoạt động như thế nào.
Chúng tôi sẽ không cần luận án Fielding và chúng tôi sẽ không cần đánh giá các API của mình dựa trên
các ràng buộc Fielding, bởi vì chúng tôi đã có một ví dụ thực tế thành công về hệ thống mà chúng tôi
muốn tạo.
Web gần như đủ tốt cho mục đích của chúng tôi, nhưng chưa hoàn toàn. Chúng tôi muốn phát triển dựa
trên sự thành công của nó, nhưng chúng tôi không thể sử dụng những nguyên tắc giống hệt nhau. Giải
pháp nằm ở nửa đầu của luận án Fielding, phần này cho thấy ngay từ đầu các ràng buộc Fielding đến từ
1. Viết ra tất cả các đặc tính kiến trúc mà hệ thống của bạn nên có.
354 | Phụ lục C: Hướng dẫn về Luận án Fielding dành cho nhà thiết kế API
Machine Translated by Google
2. Tìm ra những tài sản nào bạn thực sự cần và những tài sản nào bạn sẵn sàng
để hy sinh.
3. Đưa ra một tập hợp các ràng buộc về kiến trúc sẽ mang lại cho hệ thống của bạn sự hỗ trợ
4. Thiết kế một bộ giao thức và các tiêu chuẩn khác phối hợp với nhau để thể hiện
5. Trong suốt nhiều thập kỷ, khi các vấn đề trở nên rõ ràng, hãy lặp lại các bước 2—4 (HTTP 0.9, HTTP
API Web giới thiệu một hạn chế mới: khoảng cách ngữ nghĩa. Chúng tôi đã tranh luận về khoảng cách ngữ
nghĩa trong hơn một thập kỷ và mặc dù chúng tôi đã đạt được sự đồng thuận rằng một số hạn chế của Fielding
vẫn có liên quan nhưng vẫn chưa tìm ra giải pháp. Để xem bạn đang đứng về phía nào trong lập luận, bạn
phải quyết định xem thuộc tính kiến trúc nào của Web là quan trọng nhất đối với bạn.
Đây có phải là rào cản gia nhập thấp, đặc tính cho phép mọi người sử dụng một trang web mà không cần đào
tạo cụ thể về trang web? Đó có phải là khả năng mở rộng, đặc tính cho phép một trang web được thiết kế
lại hoàn toàn mà không ảnh hưởng đến khách hàng của nó? Hay đó là quy mô Internet, đặc tính cho phép mọi
người sử dụng trình duyệt web mà họ lựa chọn và nâng cấp theo tốc độ của riêng họ?
Tôi đã chọn khả năng mở rộng và quy mô Internet, với chi phí là rào cản gia nhập thấp. Đó là bởi vì
khoảng cách ngữ nghĩa tự nó đã làm tăng rào cản gia nhập. Bất kỳ API nào cũng khó sử dụng hơn một trang
web tương đương. Thiết kế dựa trên siêu phương tiện sẽ nâng cao rào cản gia nhập nhưng nó mang lại cho
bạn khả năng mở rộng và quy mô Internet, những điều cần thiết về lâu dài
thuật ngữ.
Và đây là một dự án dài hạn. Chúng ta có thể gỡ bỏ rào cản gia nhập bằng các thư viện máy khách thông
minh hơn, với các thỏa thuận sử dụng các loại siêu phương tiện phổ biến và các nhóm ngữ nghĩa ứng dụng
chung. Nhưng nếu chúng ta từ bỏ khả năng mở rộng và quy mô Internet, chúng ta sẽ không bao giờ lấy lại
được chúng.
Ngữ nghĩa ứng dụng của biểu diễn giải thích tài nguyên Kho lưu trữ các phản hồi HTTP, được sử dụng để cải
cơ bản dưới dạng các khái niệm trong thế giới thực. Hai thiện hiệu suất của máy khách. Đôi khi, khách hàng có
tài liệu HTML có thể sử dụng chính xác các thẻ giống thể sử dụng lại phản hồi được lưu trong bộ nhớ đệm thay
nhau nhưng có ngữ nghĩa ứng dụng hoàn toàn khác nhau— vì gửi yêu cầu qua mạng.
Nếu định dạng tài liệu được thiết kế để thể hiện các đổi cùng với phần còn lại của quá trình triển khai máy
khái niệm trong thế giới thực, chúng ta có thể nói rằng chủ. API hiếm khi thực hiện ràng buộc này do lo ngại
bản thân định dạng đó có ngữ nghĩa ứng dụng. Định dạng về bảo mật.
trò chơi mê cung. Định dạng HTML có ngữ nghĩa ứng dụng
sự kết nối
của một tài liệu con người có thể đọc được.
Thuật ngữ của tôi cho ràng buộc hypermedia (qv). Tôi
thích thuật ngữ này hơn vì nó tập trung vào điều tôi
tâm trí. Định dạng HAL không có ngữ nghĩa ứng dụng để
thấy quan trọng: các tài nguyên đó được “kết nối” với
nói đến: mỗi người dùng phải cung cấp ngữ nghĩa của
nhau bằng cách chuyển đổi trạng thái an toàn..
riêng họ.
Thuật ngữ “ngữ nghĩa ứng dụng” được phát minh ra cho
hội thảo
cuốn sách này. Nó không phải là một tiêu chuẩn hóa
Một quy trình được vi tính hóa để biến một URL thành
thuật ngữ.
một bản trình bày. Đối với http: URL, hội thảo có nghĩa
trạng thái ứng là gửi yêu cầu HTTP GET tới URL.
dụng Thông tin về đường dẫn của máy khách thông qua
API là trạng thái ứng dụng. Hầu hết khách hàng đều bắt
liên kết
đầu ở cùng một trạng thái, tại “trang chủ” của API. Khi
nhúng Một liên kết mà khi được kích hoạt sẽ thêm vào
chúng đưa ra những lựa chọn khác nhau, chúng kích hoạt
trạng thái ứng dụng của khách hàng thay vì thay thế nó.
các biện pháp kiểm soát siêu phương tiện khác nhau,
Các liên kết nhúng thường được kích hoạt tự động, như
chúng kết thúc ở những vị trí khác nhau và trạng thái
với <img> của HTML và
ứng dụng của chúng cũng khác nhau.
357
Machine Translated by Google
Phương thức
thẻ <script> . Ngược lại với liên kết ngoài và xem
thêm sự loại trừ. HTTP Còn được gọi là “động từ HTTP”. Đó là một phần
của yêu cầu HTTP thông báo cho máy chủ, ở mức độ rất
thực thể-cơ thể
cơ bản, những gì máy khách muốn thực hiện với một
Tài liệu được liên kết với HTTP
nguồn.
yêu cầu hoặc phản hồi. Thông thường, tài liệu này là
hypermedia Bất kỳ quá trình chuyển đổi trạng thái an toàn (qv) nào cũng
Hypermedia là dữ liệu được gửi từ máy chủ đến máy bình thường.
hệ liên kết Một chuỗi được liên kết với điều khiển
hypermedia làm công cụ của trạng thái
hypermedia. Mối quan hệ liên kết giải thích quá trình
ứng dụng Một trong những hạn chế của Fielding. Tôi gọi
chuyển đổi trạng thái nào sẽ xảy ra nếu máy khách kích
tắt là “hạn chế hypermedia”. Máy chủ điều khiển trạng
hoạt điều khiển. Mối quan hệ liên kết có thể mô tả sự
thái của máy khách bằng cách gửi một “menu” hypermedia
thay đổi trong trạng thái ứng dụng (chẳng hạn như tiếp
chứa các tùy chọn mà máy khách có thể tự do lựa chọn.
theo và trước đó) hoặc thay đổi trạng thái tài nguyên
cầu HTTP (hoặc nhóm yêu cầu) mà khách hàng có thể thực
giải thích sự chuyển đổi trạng thái sẽ xảy ra nếu máy phương tiện Loại phương tiện (còn gọi là loại nội dung
khách thực hiện yêu cầu HTTP đó. hoặc loại MIME) là một chuỗi ngắn xác định định dạng
của tài liệu. Khi bạn biết loại phương tiện của tài
Bạn cũng có thể hiểu được ngữ nghĩa ứng dụng và giao
Một số điều khiển hypermedia được cho là sẽ được kích
thức của nó.
hoạt tự động (như thẻ <img> của HTML ). Những cái khác
sẽ chỉ được kích hoạt nếu khách hàng quyết định kích liên kết ngoài
hoạt chúng (như thẻ <a> của HTML ). Một điều khiển siêu phương tiện thay thế trạng thái
ứng dụng của khách hàng bằng một trạng thái hoàn toàn
chứa một liên kết ra ngoài. Tương phản liên kết tất cả các yêu cầu HTTP được xác định bởi các điều khiển
nhúng. siêu phương tiện của nó.
BÀI ĐĂNG quá tải Khi một định dạng tài liệu cho phép điều khiển siêu
Sử dụng phương thức HTTP POST để kích hoạt chuyển đổi phương tiện, chúng ta nói rằng bản thân định dạng đó có
trạng thái có thể thực hiện bất kỳ điều gì. ngữ nghĩa giao thức. Ví dụ: chúng ta có thể nói rằng ngữ
Ngược lại POST-to-append. nghĩa giao thức của HTML cho phép các yêu cầu GET và
Sử dụng phương thức HTTP POST để tạo một tài nguyên mới
“bên dưới” một tài nguyên khác. Ngược lại POST bị quá Thuật ngữ “ngữ nghĩa giao thức” được phát minh ra cho
tải. cuốn sách này. Nó không phải là một thuật ngữ tiêu chuẩn.
hồ sơ Biểu diễn
Một hồ sơ giải thích các bit ngữ nghĩa của tài liệu không Biểu diễn là một phần dữ liệu mô tả trạng thái của một
được loại phương tiện của nó bao hàm. Hồ sơ giống như tài nguyên. Thông thường, một biểu diễn là một tài liệu
một cặp kính ma thuật tiết lộ những khía cạnh chưa từng được sử dụng làm nội dung thực thể của một yêu cầu hoặc
thấy trước đây về ý nghĩa của tài liệu. phản hồi HTTP. Trong một số trường hợp, có thể hữu ích
khi coi toàn bộ thông báo yêu cầu hoặc phản hồi dưới
chuẩn HTML về việc mô tả con người. Hồ sơ thực hiện công Khi máy chủ gửi bản trình bày tới máy khách, nó sẽ mô
việc bổ sung. tả trạng thái hiện tại của tài nguyên. Khi một máy khách
gửi một biểu tượng đến máy chủ, nó đang cố gắng sửa đổi
Một khách hàng không hiểu một hồ sơ vẫn có thể phân tích
nguồn
một tài liệu và lấy thông tin từ nó, dựa trên sự hiểu
biết của nó về loại phương tiện của tài liệu. Nhưng nó Tài nguyên có thể là bất cứ thứ gì: một trang web, một
sẽ thiếu một lớp ngữ nghĩa bổ sung. người, tên người đó, số đo cân nặng của anh ta vào một
ngày nhất định, mối quan hệ của anh ta với một người
khác… bất cứ thứ gì. Hạn chế duy nhất là tài nguyên phải
ngữ nghĩa giao
có URI riêng. Không có URI thì không còn gì để nói.
thức Điều khiển siêu phương tiện nói về một yêu cầu HTTP
(hoặc một nhóm yêu cầu) mà khách hàng có thể thực hiện.
Đây là ngữ nghĩa giao thức của nó. Chúng cho bạn biết
tập hợp con nào của giao thức HTTP hữu ích trong tình Một khách hàng sẽ không bao giờ tương tác trực tiếp với
huống này. một tài nguyên. Nó chỉ nhìn thấy các mô tả về trạng thái
ứng dụng. Ngữ nghĩa ứng dụng giải thích theo thuật ngữ
thực tế những thông tin nào cần được cung cấp cho máy trạng thái
chủ cùng với yêu cầu HTTP, điều gì sẽ xảy ra để phản hồi tài nguyên Các biểu diễn có đầy đủ trạng thái tài
yêu cầu hoặc cách khách hàng nên kết hợp phản hồi vào nguyên. Biểu diễn truyền tải thông tin về trạng thái
quy trình làm việc của mình. hiện tại của tài nguyên (khi máy chủ gửi biểu diễn đến
máy khách) hoặc về trạng thái mới mong muốn của tài
nguyên (khi máy khách gửi biểu diễn đến máy chủ).
Khi một tài liệu chứa các điều khiển siêu phương tiện,
chúng tôi nói rằng bản thân tài liệu đó có ngữ nghĩa
giao thức. Tài liệu cho phép Trong thế giới API web, trạng thái tài nguyên thường
(chẳng hạn như tên của một người), với mỗi phần được mô tả Thuật ngữ “khoảng cách ngữ nghĩa” được phát minh ra cho cuốn
sách này. Nó không phải là một thuật ngữ tiêu chuẩn. Chúng tôi gọi
bằng một bộ mô tả ngữ nghĩa. Nhưng đây là sự thật về cách
chúng ta viết chương trình máy tính hơn là sự thật về REST. thách thức thu hẹp khoảng cách ngữ nghĩa thách thức ngữ nghĩa.
loại tài Một trong những hạn chế của Fielding. Kết quả cuối cùng của
giới thực đằng sau một tài nguyên (ngược lại với dữ liệu ent chịu trách nhiệm về tất cả trạng thái ứng dụng và máy
trong các biểu diễn của nó), bạn có thể sử dụng một loại tài chủ chịu trách nhiệm về tất cả trạng thái tài nguyên.
nguyên. Loại tài nguyên là một URI phân loại tài nguyên theo
chuyển trạng thái
danh mục trừu tượng như người (hoặc chính xác hơn là http://
Một sự thay đổi trong trạng thái ứng dụng hoặc tài nguyên.
schema.org/Person hoặc http://xmlns.com/foaf/0.1/Person).
Một mối quan hệ liên kết là tên của một trạng thái chuyển tiếp
sự. Điều khiển hypermedia giải thích yêu cầu HTTP nào sẽ
an toàn
Việc kích hoạt quá trình chuyển đổi trạng thái an toàn sẽ có
nhúng Các
tác động tương tự đối với trạng thái tài nguyên như không
liên kết nhúng (qv) nhúng một biểu diễn này vào một biểu
làm gì cả. Các phương thức HTTP GET, HEAD và OPTIONS được
diễn khác. Khi một trang web
cho là an toàn.
trình duyệt gặp thẻ <img> trong tài liệu HTML, nó thực hiện
yêu cầu HTTP cho hình ảnh nhị phân và tự động chèn kết xuất
thông báo tự mô tả Một hình ảnh đó vào kết xuất của tài liệu HTML. Không cần phải
trong những ràng buộc của Fielding. Nó nói rằng tất cả thông đồng bộ hóa hình ảnh và tài liệu HTML; họ thậm chí có thể ở
tin cần thiết để hiểu một thông báo yêu cầu hoặc phản hồi trên các máy chủ khác nhau.
đều được chứa trong (hoặc ít nhất là được liên kết từ) chính
Một chuỗi ngắn đặt tên cho một phần trạng thái tài nguyên Một trong những hạn chế của Fielding. Một thuật ngữ chung
cung cấp một mô tả mà con người có thể đọc được và các hồ sơ các đặc điểm” mô tả hoạt động của Web: xác định tài nguyên,
khác nhau có thể đặt các tên khác nhau cho cùng một thông thao tác tài nguyên thông qua các biểu diễn, thông báo tự mô
tin: hãy xem xét “tên đã cho” (hCard), “tên đã tả và siêu phương tiện như động cơ của trạng thái ứng dụng.
Thuật ngữ “bộ mô tả ngữ nghĩa” được phát minh ra cho cuốn hầu hết những gì mọi người nghĩ đến khi họ nghĩ về “REST”.
URI
khoảng cách
ngữ nghĩa Khoảng cách giữa cấu trúc của một tài liệu và ý Một chuỗi xác định duy nhất một tài nguyên.
nghĩa trong thế giới thực của nó—ngữ nghĩa ứng dụng của nó.
URL
Các loại phương tiện, hồ sơ có thể đọc được bằng máy và tài
Một URI có thể được hủy đăng ký để có được một đại diện.
liệu mà con người có thể đọc được sẽ thu hẹp khoảng cách
Không phải mọi URI đều là URL.
ngữ nghĩa theo nhiều cách khác nhau, nhưng việc thu hẹp
Không có cách nào để hủy đăng ký URI urn:isbn:9781449358063,
khoảng cách luôn cần có sự can thiệp của con người tại một
vì vậy đó không phải là URL.
số điểm.
Mục lục
Chúng tôi muốn nghe đề xuất của bạn để cải thiện chỉ mục của chúng tôi. Gửi email đến index@oreilly.com.
361
Machine Translated by Google
Wiki vi định dạng, 230 hồ CoAP (Giao thức ứng dụng ràng buộc)
trạng thái ứng dụng, cấu trúc phản hồi yêu cầu, 290 yêu cầu,
10 định nghĩa, 357 288 phản hồi
thức xuất bản Atom Các tin nhắn trong, 289 cách sử
điều cơ bản, 207 mẫu bộ sưu tập trong, theo yêu cầu
rộng, 104 tiêu chuẩn blog trong World Wide Web, 352, 354
của xvii , 105 tiêu đề Slug trong, 317 tiêu điểm của, 25 điều
OAuth 1.0, 252 với OAuth 2.0, 256 so với AtomPub, 102
về, 91 phương
thức GET, 100 phân
Tiêu đề Mã hóa nội dung, 246, 323 Tiêu đề con người có thể đọc được, 134,
ngôn ngữ nội dung, 323 Tiêu đề độ dài 172 tầm quan trọng
nội dung, 323 Tiêu đề vị trí nội của, 197 được cải thiện cho đặc tả HTTP mới, 238
dung, 218, 324 Tiêu đề nội dung-MD5, 324 JSON-LD (JSON để liên kết dữ liệu), 151 quan hệ
Tiêu đề phạm vi nội dung, 324 liên kết và 139 liên kết
Tiêu đề loại nội dung, 20, 324 đến hồ sơ, 135 vị trí, 134
Định dạng liên kết CoRE, phương tiện hồ sơ, 136 hồ sơ cho, 135
292 tiêu chuẩn ngữ nghĩa giao
công ty, ứng dụng khách API thức và 137 bộ mô tả ngữ nghĩa và
loại trình thu thập thông tin 140 điều khiển siêu phương tiện có
xxiv , 88 thông tin xác thực, mục đích đặc biệt , 136 quan hệ liên kết không an
ứng dụng khách so với cá nhân, 250 lớp toàn và, 140
CSS, 113 Định dạng XMDP (XHTML Meta Data Profile) dành cho
141
192 loại phương tiện mới, 183 E tài liệu nhúng, 154 định nghĩa liên
tùy chỉnh, 182 thiết kế URL trong, Điều khiển siêu phương tiện HTML cho, 111
Digest, 251 điện toán phân tán, World dung thực thể, 358
phân phối hypermedia, tài liệu 343, 353 thông báo lỗi, 295, 296 (xem
thêm mã trạng thái)
ALPS (Ngữ nghĩa giao thức cấp ứng dụng), 143 ngữ Tiêu đề ETag, 244, 326
nghĩa ứng Mong đợi tiêu đề, 326
thức HEAD, 40
Phương thức GET, nghĩa ứng dụng plug-in cho, 111 thuộc tính
rel, 111
6 là phương thức an toàn,
Tiện ích mở rộng HTTP
18, 25 GET có điều kiện, 242,
Phương pháp LIÊN KẾT, 258
248 chi tiết,
Phương pháp PATCH, 257
34 chức năng của,
Phương thức UNLINK, 258
33 trong thiết kế dựa trên bộ sưu
WebDAV, 259
tập, 100 GET một
tiêu đề HTTP
phần, 246 đường
Chấp nhận, 239, 319
dẫn, 247 với thẻ <form>, 48, 111
Chấp nhận-Charset, 319
Giao thức Gopher, 14
Mã hóa chấp nhận, 245, 319
gzip, 245
Ngôn ngữ chấp nhận, 239, 320
HATEOAS (hypermedia là động cơ của trạng thái ứng dụng) Bố trí nội dung, 322
định nghĩa về, Mã hóa nội dung, 246, 323
358 ví dụ về, 14 Nội dung-Ngôn ngữ, 323
định dạng hCard, Độ dài nội dung, 323
113 Nội dung-Vị trí, 218, 324
ETag, 244, 326 đàm phán nội dung và 239 ngăn cản
Hết hạn, 242, 327 thực, 249–257 tiêu đề, 238 tiện ích mở
Từ, 327 rộng HTTP, 257 menu hypermedia,
Thử lại sau, 335 HTTP: Hướng dẫn dứt khoát (Gourley và Tot-ty), 238 tài
Set-Cookie, 336 liệu con
Sên, 336 người có thể đọc được, 122, 134, 149 Hydra, 276 định
Chuyển-Mã Hóa, 337 loại, 317 của, 48, 237, 358 được phân
Tác nhân người dùng, 338 Fielding và, 348 ngôn ngữ
Khác nhau, 339 hypermedia chung (xem HTML) hướng dẫn các yêu cầu
Qua, 339 HTTP, 52 định dạng HTML cho,
WWW-Xác thực, 250, 340 tiêu đề liên kết và, 51, 218
Thông báo HTTP, tổng quan về, 33 đường dẫn và, 247 hiểu biết
Lựa chọn phương kém về, xviii thiết kế
thức HTTP, 42 hypermedia thuần túy, 109 Mẫu URI
định nghĩa, 358 chi và, 49 URI so với URL, 50
tiết, 34–42 ví dụ
về, 6
tính hữu dụng của, 45, 52, 67, Tiêu đề If-Match, 328
nghĩa, 358 ví dụ về, 46 trong Cơ quan cấp số hiệu Internet (IANA), 63, 230
World Wide
cho, 52 định dạng hypermedia Atom Internet-Bản nháp, xxv, 34, 40, 242, 287
225–229 HAL (Ngôn ngữ ứng dụng siêu văn bản), liên kết
liệu trang chủ JSON, 219 tiêu đề của, 95 thuộc tính itemscope,
Mẫu liên kết, 220 tiêu đề vị trí, 116 thuộc tính loại mục, 116
218 Mê cung+XML, 200
phương thức
CHỌN, 40 chức
Tài liệu máy đọc được M , 122, 141 năng của, 33 định
Ví dụ về Mê cung+XML ví dụ về 54 điều
Lệnh gọi API và, 67 khiển siêu phương tiện HTML cho 110 POST bị
quá tải
trạng thái ứng dụng, 64 ứng
dụng khách tự động cho, 74, 76 định nghĩa, 359 ví
mục tiêu, 59
ứng dụng khách do con người điều
P
khiển, 68–72 mối quan
phân trang, 101
hệ liên kết trong,
Chi tiết về phương
62 loại phương tiện, 60
pháp PATCH, 38, 257
mắt chuột -xem trong, 61 thách
chức năng của, 34
thức ngữ nghĩa
trong thiết kế dựa trên bộ sưu tập,
và, 60 máy chủ cho, 72 phần mở
101 thông tin xác thực cá
rộng tiêu
nhân, 250 tiêu chuẩn cá nhân,
chuẩn, 77–80 định nghĩa
đường ống xxiv , 247
loại phương tiện, 20, 358 trong quy trình
Hàm phương thức
thiết kế, 167, 170, 176, 183 nội
POST của, 24, 33 với
dung đàm phán và, 240
thẻ <form>, 48, 111
đăng ký, 184 phiên
Định nghĩa POST-to-
bản của , 186
append của, 359 chi
thành viên, 93 tin nhắn, tự mô tả, 5, 347,
tiết, 37 trong
354 hồ sơ siêu dữ liệu, 141
thiết kế dựa trên bộ sưu tập, 100
siêu từ vựng, 270 API tiểu
Tiêu đề thực dụng, 332
blog, xvii microdata, 116, 136
Thích tiêu đề hơn, 333
vi định dạng, 113, 138,
Tiêu đề ứng dụng ưu tiên, 333 tài liệu
230
chi tiết vấn đề, 201, 296 hồ sơ
Các loại MIME (xem các loại phương
tên, đối chiếu trong quá trình thiết kế, 164, 174 359 tài liệu nhúng, 154
ngữ nghĩa giao thức và 137 nguyên xxi , 11 thay đổi bằng
xuất bản, 170 bộ HTML, 117, 119
mối quan hệ liên kết không an toàn tài nguyên sưu tập, 93
Định dạng XMDP (Hồ sơ siêu dữ liệu XHTML), tả, 263 ví dụ, 2
141 nhận dạng, 346,
định nghĩa ngữ nghĩa 354 trong quá trình thiết
giao thức, 359 tầm kế, 178 thao tác thông
quan trọng của, 33 qua biểu diễn, 346,
trong thiết kế dựa trên bộ sưu 354
tập, 100 hồ sơ nhiều cách thể hiện, 32, 239 mối quan
và, 137 so với ngữ nghĩa ứng hệ giữa, 54 mã phản hồi, 4,
dụng, 57 tiêu đề xác thực proxy, 19, 238, 295 (xem thêm phản hồi
334 tiêu đề ủy quyền proxy, 334 xuất HTTP) (xem thêm mã trạng
bản, trong quá trình thiết kế, 170 thái) tiêu đề phản hồi,
chi tiết 20 (xem thêm tiêu đề
phương pháp HTTP)
PUT của , 37 Kiến trúc RESTful có
chức năng, 33 trong thiết kế dựa trên bộ sưu tập, 101 khả năng thích ứng với sự thay
đổi, xvi là từ thông dụng tiếp thị,
xviii, 29 Ràng buộc trường và, 341,
348 tiêu đề HTTP trong, 317–
Tiêu đề phạm vi R , 247, 340 giao diện thống nhất
334 RDF (Khung mô tả tài nguyên) cơ bản về,
trong, 345 so với API dựa
264 chiến lược
trên SOAP, xvii Dịch vụ web RESTful (Richardson và Ruby ),
mô tả so với biểu diễn và, 264, 268 Lược đồ RDF, xvii
270 loại
Tiêu đề thử lại sau, 335
tài nguyên trong,
RFC 2616, 238
269 cách xử lý URL, 265
RFC (yêu cầu bình luận), xxv, 238
tính hữu ích của, 266
Richardson, Leonard, xvii
tiêu đề người giới
Ruby, Sam, xvii
thiệu, 335 đã đăng ký