RESTful Web APIs中文版

序 ................................................................................xix
前言 .............................................................................xxi
第1 章 网上冲浪 ............................................................ 1
场景1 ：广告牌 ......................................................................................................2
资源和表述 .....................................................................................................2
可寻址性 .........................................................................................................3
· · · · · · (更多)

序 ................................................................................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
· · · · · · (收起)