Web API 的設計與開發 (Web API : the Good Parts)

水野貴明（作者）
1973年出生於東京。自由軟件開發者兼技術書作譯者。是JavaScript：The Good Parts、Third-Party JavaScript、 High Performance JavaScript、The Principles of Object-Oriented JavaScript等圖書的日文版譯者，著有《Web應用程序測試方法》（合著）。

盛榮（譯者）
曾就職於愛立信、Autodesk等公司，長期從事軟件、因特網技術相關領域的研發、測試等工作。熱愛技術，對IT相關的新聞、歷史等有濃厚興趣。

譯者序
前言

第1章什麼是WebAPI 1 
1.1 WebAPI的重要性3 
1.1.1通過API才能使用的在線服務出現5 
1.1.2移動應用與API 7 
1.1.3 API的經濟學7 
1.2各種各樣的API模式8 
1.2.1將已發布的Web在線服務的數據或功能通過API公開8 
1.2.2將附加在其他網頁上的微件公開9 
1.2.3構建現代Web應用10 
1.2.4開發智能手機應用11 
1.2.5開發社交遊戲11 
1.2.6公司內部多個系統的集成12 
1.3應該通過API公開什麼12 
1.3.1公開API是否會帶來風險13 
1.3.2公開API能得到什麼14 
1.4設計優美的WebAPI的重要性15 
1.4.1設計優美的WebAPI易於使用15 
1.4.2設計優美的WebAPI便於更改16 
1.4.3設計優美的WebAPI健壯性好16 
1.4.4設計優美的WebAPI不怕公之於眾16 
1.5如何美化WebAPI 17 
1.6 REST與WebAPI 18 
1.7作為目標對象的開發人員數量與API的設計思想19 
1.8小結20 

第2章端點的設計與請求的形式21 
2.1設計通過API公開的功能21 
2.2 API端點的設計思 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端點的設計37 
2.4.1訪問資源的端點設計的註意事項41 
2.4.2註意所用的單詞43 
2.4.3不使用空格及需要編碼的字符43 
2.4.4使用連接符來連接多個單詞44 
2.5搜索與查詢參數的設計45 
2.5.1獲取數據量和獲取位置的查詢參數46 
2.5.2使用相對位置存在的問題47 
2.5.3使用絕對位置來獲取數據48 
2.5.4用於過濾的參數49 
2.5.5查詢參數和路徑的使用區別52 
2.6登錄與OAuth2.053 
2.6.1 accesstoken的有效期和更新58 
2.6.2其他GrantType 59 
2.7主機名和端點的共有部分61 
2.8 SSKDs與API的設計63 
2.9 HATEOAS和RESTLEVEL3API 64 
2.9.1 RESTLEVEL3API的優點67 
2.9.2 RESTLEVEL3API 67 
2.10小結68 

第3章響應數據的設計69 
3.1數據格式69 
3.2使用JSONP 74 
3.2.1支持JSONP的操作方法75 
3.2.2 JSONP與錯誤處理77 
3.3數據內部結構的思考方法 79 
3.3.1讓用戶來選擇響應的內容81 
3.3.2封裝是否必要82 
3.3.3數據是否應該扁平化83 
3.3.4序列與格式85 
3.3.5該如何返回序列的個數以及是否還有後續數據88 
3.4各個數據的格式90 
3.4.1各個數據的名稱90 
3.4.2如何描述性別數據92 
3.4.3日期的格式95 
3.4.4大整數與JSON 96 
3.5響應數據的設計97 
3.6出錯信息的表示98 
3.6.1通過狀態碼來表示出錯信息98 
3.6.2向客戶端返回詳細的出錯信息99 
3.6.3如何填寫詳細的出錯信息101 
3.6.4發生錯誤時防止返回HTML 102 
3.6.5維護與狀態碼102 
3.6.6需要返回意義不明確的信息時103 
3.7小結104 

第4章最大程度地利用HTTP協議規範105 
4.1使用HTTP協議規範的意義105 
4.2正確使用狀態碼107 
4.2.12字頭狀態碼：成功109 
4.2.23字頭狀態碼：添加必要的處理111 
4.2.3當客戶端請求發生問題時113 
4.2.45字頭狀態碼：當服務器端發生問題時115 
4.3緩存與HTTP協議規範116 
4 .3.1過期模型117 
4.3.2驗證模型120 
4.3.3啟發式過期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來定義新的數據格式的情況132 
4.4.5媒體類型與安全性133 
4.4.6請求數據與媒體類型134 
4.5同源策略和跨域資源共享136 
4.5.1 CORS基本的交互137 
4.5.2事先請求138 
4.5.3 CORS與用戶認證信息139 
4.6定義私有的HTTP首部139 
4.7小結141 

第5章開發方便更改設計的WebAPI 143 
5.1方便更改設計的重要性143 
5.1.1公開發布的API 144 
5.1.2面向移動應用的API 145 
5.1 .3 Web服務中使用的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應該採用什麼方法153 
5.3版本變更的方針153 
5.4終止提供API 155 
5.4.1案例學習：Twitter廢除舊版本的API 156 
5.4.2預先準備好停止服務時的規範156 
5.4.3在使用條款中寫明支持期限159 
5.5編排層160 
5.6小結162 

第6章開發牢固的WebAPI 163 
6.1讓WebAPI變得安全163 
6.2非法獲取服務器端和客戶端之間的信息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篡改參數181 
6.4.2請求再次發送183 
6.5同安全相關的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應對 大規模訪問的對策191 
6.6.1限制每個用戶的訪問192 
6.6.2限速的單位194 
6.6.3應對超出上限值的情況195 
6.6.4向用戶告知訪問限速的信息198 
6.7小結204 
附錄A公開WebAPI的準備工作205 
A.1提供API文檔205 
A.2提供沙盒API 206 
A.3 APIConsole 207 
A.4提供SDK 209 
附錄B WebAPI確認清單211