序 ................................................................................xix
前言 .............................................................................xxi
第1 章 網上衝浪 ............................................................ 1
場景1 ：廣告牌 ......................................................................................................2
資源和錶述 .....................................................................................................2
可尋址性 .........................................................................................................3
場景2 ：主頁 .........................................................................................................3
短會話（Short Session） ..................................................................................5
自描述消息（self-descriptive message） ..........................................................5
場景3 ：鏈接 .........................................................................................................6
標準方法 .........................................................................................................8
場景4 ：錶單和重定嚮 ..........................................................................................9
應用狀態（Application State） ....................................................................... 11
資源狀態（resource state） ............................................................................12
連通性（connectedness） ...............................................................................13
與眾不同的Web ............................................................................................14
Web API 落後於Web ....................................................................................15
語義挑戰 .......................................................................................................16
第2 章 一個簡單的API ................................................ 17
HTTP GET ：安全的投注 .....................................................................................18
如何讀取HTTP 響應 ...........................................................................................19
JSON ....................................................................................................................20
Collection+JSON ..................................................................................................21
嚮API 寫入數據 ..................................................................................................23
HTTP POST: 資源是如何生成的 ..........................................................................24
由約束帶來解放 ...................................................................................................26
應用語義所産生的語義鴻溝 ................................................................................27
第3 章 資源和錶述 ...................................................... 29
萬物皆可為資源 ...................................................................................................30
錶述描述資源狀態 ...............................................................................................30
往來穿梭的錶述 ...................................................................................................31
資源有多重錶述 ...................................................................................................32
HTTP 協議語義（Protocol Semantics） .............................................................33
GET ...............................................................................................................35
DELETE ........................................................................................................36
冪等性（Idempotence） ..................................................................................36
POST-to-Append ............................................................................................37
PUT ...............................................................................................................38
PATCH ..........................................................................................................39
LINK 和UNLINK .........................................................................................40
HEAD ............................................................................................................40
OPTIONS ......................................................................................................41
Overloaded POST ..........................................................................................41
應該使用哪些方法？ ...........................................................................................42
第4 章 超媒體 ............................................................. 45
將HTML 作為超媒體格式...................................................................................46
URI 模闆 ..............................................................................................................49
URI vs URL .........................................................................................................50
Link 報頭 .............................................................................................................51
超媒體的作用 ......................................................................................................52
引導請求 .......................................................................................................52
對響應做齣承諾 ............................................................................................54
工作流控製 ...................................................................................................55
當心冒牌的超媒體！ ...........................................................................................56
語義挑戰：我們該怎麼做？ ................................................................................57
第5 章 領域特定設計 ................................................... 59
Maze+XML ：領域特定設計 ................................................................................60
Maze+XML 是如何工作的 ...................................................................................61
鏈接關係 .......................................................................................................62
訪問鏈接來改變應用狀態 .............................................................................64
迷宮集閤 ..............................................................................................................65
Maze+XML 是API 嗎？ ......................................................................................67
客戶端1 ：遊戲 ....................................................................................................68
Maze+XML 服務器 ..............................................................................................72
客戶端2 ：地圖生成器 ........................................................................................74
客戶端3 ：吹牛者 ................................................................................................76
客戶端做自己想要做的事 ....................................................................................77
對標準進行擴展 ............................................................................................77
地圖生成器的缺陷 ...............................................................................................80
修復（以及修復後的瑕疵） ...........................................................................81
迷宮的暗喻 ..........................................................................................................83
解決語義鴻溝 ......................................................................................................83
領域特定設計在哪裏？ ........................................................................................83
最終的奬賞 ...................................................................................................84
報頭中的超媒體 ............................................................................................84
抄襲應用語義 ................................................................................................84
如果找不到相關的領域特定設計，不要自己製造 ...............................................86
API 客戶端的種類 ...............................................................................................86
人類驅動的客戶端 ........................................................................................86
自動化客戶端 ................................................................................................87
第6 章 集閤模式（Collection Pattern） ......................... 91
什麼是集閤？ ......................................................................................................93
鏈嚮子項的集閤 ............................................................................................93
Collection+JSON ..................................................................................................94
子項的錶示 ...................................................................................................95
寫入模闆（Write Template） ..........................................................................98
搜索模闆 .......................................................................................................99
一個（通用的）集閤是如何工作的 ................................................................... 100
GET ............................................................................................................. 101
POST-to-Append .......................................................................................... 101
PUT 和PATCH ............................................................................................ 101
DELETE ...................................................................................................... 102
分頁 ............................................................................................................. 102
搜索錶單 ..................................................................................................... 103
Atom 發布協議（AtomPub） .............................................................................. 103
AtomPub 插件標準 ...................................................................................... 105
為什麼不是每個人都選擇使用AtomPub ？ ................................................ 106
語義挑戰：我們應該怎麼做？ .......................................................................... 107
第7 章 純- 超媒體設計 .............................................. 111
為什麼是HTML? ............................................................................................... 111
HTML 的能力 .................................................................................................... 112
超媒體控件 ................................................................................................. 112
應用語義插件 .............................................................................................. 113
微格式 ................................................................................................................ 115
hMaze 微格式 .................................................................................................... 116
微數據 ................................................................................................................ 118
改變資源狀態 .................................................................................................... 119
為錶單添加應用語義 ................................................................................... 121
與超媒體相對是普通媒體 .................................................................................. 125
HTML 的局限性 ................................................................................................ 126
拯救者HTML5? .......................................................................................... 127
超文本應用語言 ................................................................................................. 128
Siren ................................................................................................................... 131
語義挑戰：我們現在要怎麼做？ ....................................................................... 133
第8 章 Profile ........................................................... 135
客戶端如何找尋文檔？ ...................................................................................... 136
什麼是Profile ？ ................................................................................................ 137
鏈接到Profile .................................................................................................... 137
Profile 鏈接關係 .......................................................................................... 137
Profile 媒體類型參數 .................................................................................. 138
特殊用途的超媒體控件 ............................................................................... 139
Profile 對協議語義的描述 .................................................................................. 139
Profile 對應用語義的描述 .................................................................................. 140
鏈接關係 ..................................................................................................... 141
不安全的鏈接關係 ...................................................................................... 142
語義描述符 ................................................................................................. 142
XMDP ：首個機器可讀的Profile 格式 .............................................................. 143
ALPS .................................................................................................................. 146
ALPS 的優勢 ............................................................................................... 150
ALPS 並不是萬金油 .................................................................................... 152
JSON-LD ........................................................................................................... 153
內嵌的文檔 ........................................................................................................ 156
總結 ................................................................................................................... 158
第9 章 API 設計流程 ................................................. 161
兩個步驟的設計流程 ......................................................................................... 161
七步驟設計流程 ................................................................................................. 162
第1 步：羅列語義描述符 ........................................................................... 163
第2 步：畫狀態圖 ...................................................................................... 164
第3 步：調整命名 ...................................................................................... 168
第4 步：選擇一種媒體類型 ....................................................................... 172
第5 步：編寫Profile .................................................................................. 173
第6 步：實現 .............................................................................................. 174
第7 步：發布 .............................................................................................. 174
實例：You Type It, We Post It ............................................................................ 177
羅列語義描述符 .......................................................................................... 177
畫狀態圖 ..................................................................................................... 178
調整名稱 ..................................................................................................... 179
選擇一種媒體類型 ...................................................................................... 180
編寫Profile ................................................................................................. 181
設計建議 ............................................................................................................ 182
資源是實現的內部細節 ............................................................................... 182
不要掉入集閤陷阱 ...................................................................................... 183
不要從錶述格式著手 ................................................................................... 184
URL 設計並不重要 ..................................................................................... 184
標準名稱優於自定義名稱 ........................................................................... 186
設計媒體類型 .............................................................................................. 187
當你的API 改變時 ...................................................................................... 189
為現有API 添加超媒體 ..................................................................................... 194
改進基於XML 的API ................................................................................ 195
值不值得？ ................................................................................................. 196
Alice 的第二次探險 ........................................................................................... 196
場景1 ：沒有意義的錶述 ............................................................................ 196
場景2 ：Profile ............................................................................................ 198
Alice 明白瞭 ................................................................................................ 200
第10 章 超媒體動物園 ............................................... 203
領域特定格式 .................................................................................................... 204
Maze+XML ................................................................................................. 204
OpenSearch ................................................................................................. 205
問題細節文檔 .............................................................................................. 205
SVG ............................................................................................................. 206
VoiceXML ................................................................................................... 208
集閤模式的格式 ................................................................................................. 210
Collection+JSON ......................................................................................... 211
Atom 發布協議 ............................................................................................ 211
OData .......................................................................................................... 212
純超媒體格式 .................................................................................................... 219
HTML .......................................................................................................... 219
HAL ........................................................................................................... 220
Link 報頭 .................................................................................................... 222
Location 和Content-Location 報頭 ............................................................. 222
URL 列錶 .................................................................................................... 223
JSON 主文檔（Home Documents） .............................................................. 223
Link-Template 報頭 ..................................................................................... 224
WADL ......................................................................................................... 225
XLink .......................................................................................................... 226
XForms ........................................................................................................ 227
GeoJSON ：一個令人睏惑的類型 ...................................................................... 228
GeoJSON 沒有通用的超媒體控件 ............................................................... 230
GeoJSON 沒有媒體類型 ............................................................................. 232
從GeoJSON 學習到的經驗 ......................................................................... 233
語義動物園 ........................................................................................................ 234
鏈接關係的IANA 注冊錶 ........................................................................... 234
微格式WiKi ................................................................................................ 235
來自微格式Wiki 的鏈接關係 ...................................................................... 236
第11 章 API 中的HTTP ............................................ 241
新HTTP/1.1 規範 .............................................................................................. 242
響應碼 ................................................................................................................ 242
報頭 ................................................................................................................... 243
錶述選擇 ............................................................................................................ 243
內容協商（Content Negotiation） ................................................................ 243
超媒體菜單 ................................................................................................. 244
標準URL（Canonical URL） ...................................................................... 245
HTTP 性能 ......................................................................................................... 246
緩存（Caching） .......................................................................................... 246
條件GET 請求（Conditional GET） ............................................................ 247
Look-Before-You-Leap 請求 ........................................................................ 249
壓縮 ............................................................................................................. 250
部分GET 請求（Partial GET） .................................................................... 250
Pipelining .................................................................................................... 251
避免更新丟失問題 ............................................................................................. 252
認證 ................................................................................................................... 254
WWW-Authenticate 報頭和Authorization 報頭 .......................................... 255
Basic 認證 ................................................................................................... 255
OAuth 1.0 .................................................................................................... 256
OAuth 1.0 的缺點 ........................................................................................ 259
OAuth 2.0 .................................................................................................... 260
何時不采用OAuth ...................................................................................... 261
HTTP 擴展 ......................................................................................................... 261
PATCH 方法 ................................................................................................ 262
LINK 和UNLINK 方法 ............................................................................... 262
WebDAV ...................................................................................................... 263
HTTP 2.0 ..................................................................................................... 264
第12 章 資源描述和Linked Data ............................... 267
RDF ................................................................................................................... 268
RDF 將URL 作為URI 對待........................................................................ 270
什麼時候使用描述策略 ...................................................................................... 271
資源類型 ............................................................................................................ 273
RDF Schema ...................................................................................................... 274
Linked Data 運動 ............................................................................................... 277
JSON-LD ........................................................................................................... 278
將JSON-LD 作為一種錶述格式 ................................................................. 279
Hydra ................................................................................................................. 280
XRD 傢族........................................................................................................... 285
XRD 和JRD ................................................................................................ 285
Web 主機元數據文檔 .................................................................................. 286
WebFinger ................................................................................................... 287
本體動物園（Ontology Zoo） ............................................................................. 289
schema.org RDF .......................................................................................... 289
FOAF .......................................................................................................... 290
vocab.org .................................................................................................... 290
總結：描述策略生機盎然！ ....................................................................... 290
第13 章 CoAP: 嵌入式係統的REST .......................... 293
CoAP 請求 ......................................................................................................... 294
CoAP 響應 ......................................................................................................... 294
消息種類 ............................................................................................................ 295
延遲響應（Delayed Response） .......................................................................... 296
多播消息（Multicast Message） ......................................................................... 296
CoRE Link Format ............................................................................................. 297
結論：非HTTP 協議的REST ........................................................................... 298
附錄A 狀態法典 ........................................................ 301
附錄B HTTP 報頭法典 .............................................. 325
附錄C 為API 設計者準備的Fielding 論文導讀 ........... 349
詞匯錶 ....................................................................... 365
· · · · · · (
收起)
