目　錄


譯者序　xi


前言　xv


第1章　什么是Web API　1
1．1　Web API的重要性　3
1．1．1　通過API才能使用的在線服務(wù)出現(xiàn)　5
1．1．2　移動應(yīng)用與API　7
1．1．3　API的經(jīng)濟(jì)學(xué)　7
1．2　各種各樣的API模式　8
1．2．1　將已發(fā)布的Web在線服務(wù)的數(shù)據(jù)或功能通過API公開　8
1．2．2　將附加在其他網(wǎng)頁上的微件公開　9
1．2．3　構(gòu)建現(xiàn)代Web應(yīng)用　10
1．2．4　開發(fā)智能手機(jī)應(yīng)用　11
1．2．5　開發(fā)社交游戲　11
1．2．6　公司內(nèi)部多個系統(tǒng)的集成　12
1．3　應(yīng)該通過API公開什么　12
1．3．1　公開API是否會帶來風(fēng)險　13
1．3．2　公開API能得到什么　14
1．4　設(shè)計優(yōu)美的Web API的重要性　15
1．4．1　設(shè)計優(yōu)美的Web API易于使用　15
1．4．2　設(shè)計優(yōu)美的Web API便于更改　16
1．4．3　設(shè)計優(yōu)美的Web API健壯性好　16
1．4．4　設(shè)計優(yōu)美的Web API不怕公之于眾　16
1．5　如何美化Web API　17
1．6　REST與Web API　18
1．7　作為目標(biāo)對象的開發(fā)人員數(shù)量與API的設(shè)計思想　19
1．8　小結(jié)　20


第2章　端點的設(shè)計與請求的形式　21
2．1　設(shè)計通過API公開的功能　21
2．2　API端點的設(shè)計思想　24
2．3　HTTP方法和端點　31
2．3．1　GET方法　32
2．3．2　POST方法　33
2．3．3　PUT方法　33
2．3．4　DELETE方法　34
2．3．5　PATCH方法　35
2．4　API端點的設(shè)計　37
2．4．1　訪問資源的端點設(shè)計的注意事項　41
2．4．2　注意所用的單詞　43
2．4．3　不使用空格及需要編碼的字符　43
2．4．4　使用連接符來連接多個單詞　44
2．5　搜索與查詢參數(shù)的設(shè)計　45
2．5．1　獲取數(shù)據(jù)量和獲取位置的查詢參數(shù)　46
2．5．2　使用相對位置存在的問題　47
2．5．3　使用絕對位置來獲取數(shù)據(jù)　48
2．5．4　用于過濾的參數(shù)　49
2．5．5　查詢參數(shù)和路徑的使用區(qū)別　52
2．6　登錄與OAuth 2．0　53
2．6．1　access token的有效期和更新　58
2．6．2　其他Grant Type　59
2．7　主機(jī)名和端點的共有部分　61
2．8　SSKDs與API的設(shè)計　63
2．9　HATEOAS和REST LEVEL3 API　64
2．9．1　REST LEVEL3 API的優(yōu)點　67
2．9．2　REST LEVEL3 API　67
2．10　小結(jié)　68


第3章　響應(yīng)數(shù)據(jù)的設(shè)計　69
3．1　數(shù)據(jù)格式　69
3．2　使用JSONP　74
3．2．1　支持JSONP的操作方法　75
3．2．2　JSONP與錯誤處理　77
3．3　數(shù)據(jù)內(nèi)部結(jié)構(gòu)的思考方法　79
3．3．1　讓用戶來選擇響應(yīng)的內(nèi)容　81
3．3．2　封裝是否必要　82
3．3．3　數(shù)據(jù)是否應(yīng)該扁平化　83
3．3．4　序列與格式　85
3．3．5　該如何返回序列的個數(shù)以及是否還有后續(xù)數(shù)據(jù)　88
3．4　各個數(shù)據(jù)的格式　90
3．4．1　各個數(shù)據(jù)的名稱　90
3．4．2　如何描述性別數(shù)據(jù)　92
3．4．3　日期的格式　95
3．4．4　大整數(shù)與JSON　96
3．5　響應(yīng)數(shù)據(jù)的設(shè)計　97
3．6　出錯信息的表示　98
3．6．1　通過狀態(tài)碼來表示出錯信息　98
3．6．2　向客戶端返回詳細(xì)的出錯信息　99
3．6．3　如何填寫詳細(xì)的出錯信息　101
3．6．4　發(fā)生錯誤時防止返回HTML　102
3．6．5　維護(hù)與狀態(tài)碼　102
3．6．6　需要返回意義不明確的信息時　103
3．7　小結(jié)　104


第4章　最大程度地利用HTTP協(xié)議規(guī)范　105
4．1　使用HTTP協(xié)議規(guī)范的意義　105
4．2　正確使用狀態(tài)碼　107
4．2．1　2字頭狀態(tài)碼：成功　109
4．2．2　3字頭狀態(tài)碼：添加必要的處理　111
4．2．3　當(dāng)客戶端請求發(fā)生問題時　113
4．2．4　5字頭狀態(tài)碼：當(dāng)服務(wù)器端發(fā)生問題時　115
4．3　緩存與HTTP協(xié)議規(guī)范　116
4．3．1　過期模型　117
4．3．2　驗證模型　120
4．3．3　啟發(fā)式過期　122
4．3．4　不希望實施緩存的情況　123
4．3．5　使用Vary來指定緩存單位　123
4．3．6　Cache-Control首部　125
4．4　媒體類型的指定　127
4．4．1　使用Content-Type指定媒體類型的必要性　129
4．4．2　以x-開頭的媒體類型　130
4．4．3　自己定義媒體類型的情況　131
4．4．4　使用JSON或XML來定義新的數(shù)據(jù)格式的情況　132
4．4．5　媒體類型與安全性　133
4．4．6　請求數(shù)據(jù)與媒體類型　134
4．5　同源策略和跨域資源共享　136
4．5．1　CORS基本的交互　137
4．5．2　事先請求　138
4．5．3　CORS與用戶認(rèn)證信息　139
4．6　定義私有的HTTP首部　139
4．7　小結(jié)　141




第5章　開發(fā)方便更改設(shè)計的Web API　143
5．1　方便更改設(shè)計的重要性　143
5．1．1　公開發(fā)布的API　144
5．1．2　面向移動應(yīng)用的API　145
5．1．3　Web服務(wù)中使用的API　145
5．2　通過版本信息來管理API　146
5．2．1　在URI中嵌入版本編號　147
5．2．2　如何添加版本編號　149
5．2．3　在查詢字符串里加入版本信息　151
5．2．4　通過媒體類型來指定版本信息　152
5．2．5　應(yīng)該采用什么方法　153
5．3　版本變更的方針　153
5．4　終止提供API　155
5．4．1　案例學(xué)習(xí)：Twitter廢除舊版本的API　156
5．4．2　預(yù)先準(zhǔn)備好停止服務(wù)時的規(guī)范　156
5．4．3　在使用條款中寫明支持期限　159
5．5　編排層　160
5．6　小結(jié)　162


第6章　開發(fā)牢固的Web API　163
6．1　讓W(xué)eb API變得安全　163
6．2　非法獲取服務(wù)器端和客戶端之間的信息　165
6．2．1　用HTTPS對HTTP通信實施加密　165
6．2．2　使用HTTPS是否意味著100%安全　167
6．3　使用瀏覽器訪問API時的問題　169
6．3．1　XSS　169
6．3．2　XSRF　174
6．3．3　JSON劫持　176
6．4　思考防范惡意訪問的對策　180
6．4．1　篡改參數(shù)　181
6．4．2　請求再次發(fā)送　183
6．5　同安全相關(guān)的HTTP首部　185
6．5．1　X-Content-Type-Options　185
6．5．2　X-XSS-Protection　186
6．5．3　X-Frame-Options　186
6．5．4　Content-Security-Policy　187
6．5．5　Strict-Transport-Security　187
6．5．6　Public-Key-Pins　188
6．5．7　Set-Cookie首部和安全性　189
6．6　應(yīng)對大規(guī)模訪問的對策　191
6．6．1　限制每個用戶的訪問　192
6．6．2　限速的單位　194
6．6．3　應(yīng)對超出上限值的情況　195
6．6．4　向用戶告知訪問限速的信息　198
6．7　小結(jié)　204


附錄A　公開Web API的準(zhǔn)備工作　205
A．1　提供API文檔　205
A．2　提供沙盒API　206
A．3　API Console　207
A．4　提供SDK　209


附錄B　Web API確認(rèn)清單　211