RESTful API開發實戰 使用REST JSON XML和JAX-RS構建微服務 大資料和Web服務應用

Web 開發經典叢書
RESTful API 開發實戰
使用 REST JSON XML 和 JAX-RS 構建微服務
大資料和 Web 服務應用
[ 美 ] Sanjay Patni 著
郭理勇 譯
北 京
Sanjay Patni
Pro RESTful APIs: Design, Build and Integrate with REST, JSON, XML and JAX-RS, First Edition
EISBN： 978-1-4842-2664-3
Original English language edition published by Apress Media. Copyright © 2017 by Apress
Media. Simplified Chinese-Language edition copyright © 2018 by Tsinghua University Press.
All rights reserved.
本書中文簡體字版由 Apress 出版公司授權清華大學出版社出版。未經出版者書面許可，
不得以任何方式複製或抄襲本書內容。
北京市版權局著作權合同登記號 圖字： 01-2017-5755 -2 011-7430
本書封面貼有清華大學出版社防偽標籤，無標籤者不得銷售。
版權所有，侵權必究。侵權舉報電話： 010-62782989 13701121933
圖書在版編目 (CIP) 資料
RESTful API 開發實戰 使用 REST JSON XML 和 JAX-RS 構建微服務 大資料和 Web
服務應用/ (美) 桑傑·帕特尼(Sanjay Patni) 著；郭理勇譯. —北京：清華大學出版社， 2018
(Web 開發經典叢書)
書名原文： Pro RESTful APIs: Design, Build and Integrate with REST, JSON, XML and
JAX-RS, First Edition
ISBN 978-7-302-49211-5
Ⅰ. ①R… Ⅱ. ①桑… ②郭… Ⅲ. ①網際網路絡－網路伺服器－程式設計 Ⅳ. ①TP368.5
中國版本圖書館 CIP 資料核字(2017)第 331724 號
責任編輯：王 軍 韓宏志
封面設計：牛豔敏
版式設計：思創景點
責任校對：曹 陽
責任印製：楊 豔
出版發行： 清華大學出版社
網 址： ，
地 址： 北京清華大學學研大廈 A 座 郵 編： 100084
社 總 機： 010-62770175 郵 購： 010-62786544
投稿與讀者服務： 010-62776969， c-service@tup.tsinghua.edu.cn
質 量 反 饋： 010-62772015， zhiliang@tup.tsinghua.edu.cn
印 裝 者：三河市金元印裝有限公司
經 銷：全國新華書店
開 本： 148mm×210mm 印 張： 4.625 字 數： 125 千字
版 次： 2018 年 2 月第 1 版 印 次： 2018 年 2 月第 1 次印刷
印 數： 1～3200
定 價： 48.00 元
————————————————————————————————————————————————
產品編號： 076424-01
譯者序
每個網際網路從業人員都有這樣一種感覺： RESTful API 概念既熟悉
又陌生。熟悉的是我們能在大量開放平臺或開源專案中看到它的身影，
如常見的 OpenStack、 Kubernetes API 等，眾多企業基於開放的 RESTful
API 實現了業務擴充套件和資產獲利； 而陌生的是我們似乎很難找到 RESTful
API 的準確定義，也不瞭解如何真正在實際專案中使用它。如 REST 和
SOAP 協議到底有何區別？ RESTful API 和 HTTP 協議到底存在什麼關
系？ REST 的安全性如何保證？令人欣慰的是，拜讀 Sanjay Patni 先生
這本著作後，這些問題都將迎刃而解。
REST 一詞是由 Roy Fielding 博士於 2000 年在他的博士論文 Architectural
Styles and the Design of Network-based Software Architecture 中提出的， 實
際指一種有助於建立和組織分散式系統的架構風格。它並不是一個標準
或準則，而是一種基於資源的架構風格。基於 REST 風格構建的 API 應
該滿足 CS 模式互動、統一的資源介面、透明的分層系統以及支援無狀
態和快取等條件約束，另外需要保證 API 的安全性等。以 REST 風格構
建的系統將在效能、可擴充套件性、可移植性、可靠性等多個方面得到提升
和最佳化。
本書作者 Sanjay Patni 擁有 15 年以上的企業級軟體開發經驗，尤其
在構建 RESTful API 方面有深厚的理論研究和技術實踐背景。本書主要
從 RESTful API 的架構、設計和編碼三個方面進行深入介紹。首先闡述
REST 的基本原理和準確定義，並對 REST 與 SAOP 協議的差異，以及
XML/JSON 等資料交換格式等進行全方位比較。其次在 API 設計和建模
方面討論 API 的完整生命週期和 RESTful API 設計的最佳實踐，著重介
紹 API 組合和框架如何實現 API 的一致性和可重用性，以及 API 平臺
管理、 API 安全性和快取機制等。另外透過一個實際案例(播客 podcast)
演示如何透過 RAML 建模工具實現 API 介面的完整定義，並基於
JAX-RS 規範實際編寫了一個 REST 應用，包括 API 的外觀層、資料訪
問層以及服務層的實現等，為我們提供了可應用於企業實際場景的標準
應用示範，使得 RESTful API 不再是虛無的概念描述，而是可真正用於
企業實踐的架構風格實現。
書中很多內容都給譯者留下了深刻印象，首先在構建 RESTful API
的基礎 URL 時， 我們需要從原有的“動詞+名詞”的設計向“名詞+HTTP
動詞”的觀念轉變，使得基礎 URL 簡單而又直觀。其次在 API 組合的
管理中，我們需要解決穩定高效的 API 服務提供與企業創新(和實驗)
之間的矛盾，因此我們需要通盤考慮 API 的一致性、可重用、版本和
變更管理等。此外，企業級應用需要關注 JavaScript 跨域訪問解決方案、
OAuth 2 協議的安全性保證以及多種快取機制等。
如果希望真正透徹掌握 RESTful API 的設計理念和實際應用，譯者
建議大家主動完成每章的程式練習，程式碼其實是最好的老師。每章最後
一節都包含詳細豐富的環境設定和程式碼，使得我們更容易理解和掌握
RESTful API 的精髓。
最後要感謝清華大學出版社能給我這次寶貴的翻譯機會，把自己
關於 RESTful API 的一些學習和理解在本書中與大家分享。尤其是要
感謝本書的編輯，在本書的翻譯過程中付出了很多的心血和努力，非
常感謝他們的幫助和鼓勵。另外感謝妻子以及我的家人，感謝你們一
直以來對我的包容和理解；本書也獻給我未來的孩子，希望你會喜歡
老爸的這份禮物。
翻譯英文書籍涉及多個概念的中文釋義，我每次都力求與維基百
科、搜狗百科、百度百科等保持一致。鑑於譯者水平有限，錯誤或瑕疵
在所難免，如果對書中有任何意見或建議，也歡迎大家批評指正，我將
感激不盡！本書全部章節由郭理勇翻譯並整理， 參與翻譯的還有楊小瓊、
賀珊珊、王永勝等。
希望這本書能有力推動業界對 RESTful API 的統一定義和應用，更
好地構建統一、高效、可擴充套件的分散式系統應用。

作者簡介
Sanjay Patni 是一位注重實際成果的技術專家，
在創新技術方案與業務實際需求的協調上具有豐富
的經驗，長期致力於企業業務流程的最佳化和運營效
率的提升。
在過去五年中，他一直在 Oracle 公司的 Fusion
Apps 產品研發團隊任職，在那裡他發現了對 Fusion
Apps 程式碼管理實現自動化的機會，其中不僅涉及 GA 版本的交付發行，
還包括正在進行的演示、開發和測試程式碼。他提出並開發了自助服務
UX 用於程式碼請求和稽核，減少了 80%的手工步驟。他還發起了 12 次代
碼快速迭代，透過使用工作流和 RESTful API 等自動化技術與其他子系
統進行整合，使得大約 100 多個手工步驟實現了自動化。
在加盟 Oracle 前，他已經在軟體行業工作了 15 年以上，為不同的
行業提供關鍵技術解決方案。他的職責包括對基於 Web 的企業級產品
和解決方案提供技術創新、需求理解和分析，技術架構設計，以及推進
軟體敏捷開發等。他率先創新使用 Java 來構建業務應用，不斷推動和完
善用於企業級業務應用構建的 Java API，並獲得 Sun Microsystems 公司
頒發的獎項。
Sanjay 曾擔任 RESTful API 設計和整合培訓或課程的客座講師、技術
導師。他擁有強大的電腦科學教育背景，碩士畢業於印度理工學院(IIT)。

技術審稿人簡介
Massimo Nardone 擁有超過 22 年的安全、
Web/移動開發、雲端計算和 IT 設施等領域的豐富經
驗，對網路安全和 Android 有著狂熱的技術激情。
在過去 20 多年，他一直致力於程式設計開發和教
學，包括 Android、 Perl、 PHP、 Java、 VB、 Python、
C/C++、 MySQL 等，擁有義大利薩萊諾大學計算機
科學專業的碩士學位。
他曾經擔任專案經理、軟體工程師、研究員、首席安全架構師以及
資訊保安經理等，同時作為 PCI(國際安全標準)/SCADA(資料採集與監
視控制系統)審計員，還是 IT 安全/雲/SCADA 高階架構師等。
他的技術棧包括安全、 Android、 Cloud、 Java、 MySQL、 Drupal、
Cobol、 Perl、 Web 和移動開發、 MongoDB、 D3、 Joomla、 Couchbase、
C/C++、 WebGL、 Python、 Pro Rails、 Django CMS、 Jekyll、 Scratch 等。
他目前擔任 Cargotec Oyj 公司的首席資訊保安官，曾任赫爾辛基理
工大學(Aalto University)網路實驗室的訪問講師和主管，擁有四項國際
專利(PKI、 SIP、 SAML 和 Proxy 領域)。
Massimo 已為不同的出版公司審閱了 40 多種 IT 類圖書，同時是 Pro
Android Games 的作者之一(Apress, 2015)

前 言
眾所周知，資料庫、網站以及業務應用之間都需要資料交換。這通
過定義標準的資料格式、傳輸協議或 Web 服務來實現，常見的資料格式
有 XML(Extensible Markup Language，可擴充套件標記語言)、 JSON(JavaScript
Object Notation， JavaScript 物件表示法)等，常見的傳輸協議或 Web 服
務包括 SOAP(Simple Object Access Protocol，簡單物件訪問協議)，以及
目前更受歡迎的 REST(Representational State Transfer，表述性狀態傳遞)
等。開發人員通常需要設計自身應用的 API 介面，使得應用能整合特定
的業務邏輯並執行在作業系統或伺服器上。本書涵蓋以上資料交換概念
和通用的資料格式，並重點闡述如何構建 REST 風格的 API。
對於 Web 系統的交換來說，你將學習 HTTP 協議，包括如何使用
XML。另外本書還比較了 SOAP 和 REST，介紹無狀態轉移的概念。同
時介紹軟體 API 設計和最佳實踐等。本書後半部分將重點討論遵循
JAX-RS 標準的 RESTful API 的設計和實現，以及透過 Java API 構建
RESTful Web 服務。你將學習如何使用 JSON 和 XML 構建和使用
JAX-RS 服務，並透過實際案例使用 RESTful API 將眾多不同的資料來源
整合在一起(包括關係型資料庫和 NoSQL 資料庫等)。你將應用這些最佳
實踐完成一個小型軟體系統 API 的設計與實現，並以 RESTful API 的方
式公開可用的 API 服務。
本書適用於那些在實際專案中使用資料交換的軟體開發人員，對那
些希望瞭解資料交換方法以及如何與業務應用互動的資料專家同樣有
所幫助。書中的案例練習要求讀者具有 Java 程式設計經驗。
本書的主題包括：
• 資料交換和 Web 服務
• SOAP 與 REST，有狀態與無狀態
• XML 與 JSON
• API 設計簡介： REST 和 JAX-RS
• API 設計實踐
• 設計 RESTful API
• 構建 RESTful API
• 與 RDBMS(MySQL)進行互動
• 使用 RESTful API(比如 JSON、 XML)
• API 安全性-OAuth
• API 快取
原始碼下載
讀者可訪問 下載原始碼，也可掃
描本書封底的二維碼直接下載。
目 錄
第 1 章 RESTful API 的基本原理 ······················································1
1.1 SOAP 和 REST 的比較 ······························································ 3
1.2 Web 架構風格 ············································································ 4
1.2.1 CS 模式 ·························································································· 5
1.2.2 統一資源介面················································································· 5
1.2.3 分層系統 ························································································ 5
1.2.4 快取機制 ························································································ 6
1.2.5 無狀態 ···························································································· 6
1.2.6 按需編碼 ························································································ 6
1.2.7 HATEOAS ······················································································ 6
1.3 安全性 ························································································ 7
1.4 什麼是 REST？ ·········································································· 8
1.4.1 REST 基礎知識·············································································· 8
1.4.2 REST 基本原理·············································································· 9
1.5 小結 ·························································································· 10
第 2 章 API 設計和建模 ··································································11
2.1 API 設計策略 ··········································································· 11
2.2 API 建立流程和方法論···························································· 13
2.2.1 流程······························································································ 13
2.2.2 API 方法論··················································································· 14
2.2.3 域分析或 API 描述 ······································································ 14
2.2.4 架構設計 ······················································································ 15
2.2.5 原型設計 ······················································································ 16
2.2.6 實現······························································································ 16
2.2.7 釋出······························································································ 16
2.2.8 API 建模······················································································· 16
2.2.9 API 建模的比較 ··········································································· 18
2.3 最佳實踐 ·················································································· 19
2.3.1 保持基礎 URL 簡明直觀 ····························································· 19
2.3.2 錯誤處理 ······················································································ 20
2.3.3 版本控制 ······················································································ 22
2.3.4 區域性響應 ······················································································ 23
2.3.5 分頁······························································································ 23
2.3.6 多格式 ·························································································· 24
2.3.7 API Façade···················································································· 24
2.4 API 解決方案架構 ··································································· 24
2.4.1 移動解決方案··············································································· 25
2.4.2 雲端解決方案··············································································· 25
2.4.3 Web 端解決方案 ·········································································· 26
2.4.4 整合解決方案··············································································· 26
2.4.5 多終端解決方案··········································································· 26
2.4.6 智慧電視解決方案······································································· 26
2.4.7 物聯網 ·························································································· 26
2.5 API 解決方案中的利益相關者················································ 26
2.5.1 API 提供者··················································································· 27
2.5.2 API 消費者··················································································· 27
2.5.3 終端使用者 ······················································································ 27
2.6 小結 ·························································································· 33
第 3 章 XML 與 JSON 介紹 ····························································35
3.1 XML 簡介················································································· 35
3.1.1 XML 註釋 ···················································································· 36
3.1.2 XML 的重要性············································································· 37
3.1.3 如何使用 XML············································································· 38
3.1.4 XML 的優缺點············································································· 38
3.2 JSON 簡介················································································ 38
3.2.1 JSON 語法···················································································· 39
3.2.2 JSON 的重要性 ············································································ 40
3.2.3 如何使用 JSON ············································································ 41
3.2.4 JSON 的優缺點 ············································································ 42
3.3 XML 和 JSON 的比較······························································ 42
第 4 章 JAX-RS 介紹······································································51
4.1 JAX-RS 簡介 ············································································ 51
4.1.1 輸入和輸出內容型別 ··································································· 52
4.1.2 JAX-RS 注入················································································ 53
4.2 REST 實現················································································ 55
第 5 章 API 組合和框架 ··································································65
5.1 API 組合架構 ··········································································· 65
5.1.1 需求······························································································ 65
5.1.2 一致性 ·························································································· 65
5.1.3 可重用 ·························································································· 66
5.1.4 可定製 ·························································································· 66
5.1.5 可發現 ·························································································· 66
5.1.6 永續性 ·························································································· 66
5.2 如何實施這些需求——治理？ ··············································· 67
5.2.1 一致性 ·························································································· 67
5.2.2 可重用 ·························································································· 67
5.2.3 可定製 ·························································································· 67
5.2.4 可發現 ·························································································· 68
5.2.5 變更管理 ······················································································ 68
5.3 API 框架··················································································· 68
5.3.1 流程 API——服務層···································································· 69
5.3.2 系統 API-資料訪問物件 ······························································ 69
5.3.3 體驗 API-API 外觀······································································· 70
5.3.4 服務層實現 ·················································································· 70
第 6 章 API 平臺和資料處理器························································81
6.1 API 平臺架構 ··········································································· 81
6.1.1 我們為什麼需要 API 平臺··························································· 81
6.1.2 什麼是 API 平臺 ·········································································· 82
6.1.3 API 平臺需要具備的功能···························································· 82
6.1.4 API 平臺是如何組織的，什麼是 API 平臺的架構····················· 84
6.1.5 API 架構如何適應圍繞企業的技術架構····································· 85
6.2 資料處理器··············································································· 86
6.2.1 資料訪問物件(DAO)···································································· 86
6.2.2 命令查詢職責分離(CQRS) ·························································· 86
6.3 小結 ························································································ 101
第 7 章 API 管理和 API 客戶端 ·····················································103
7.1 外觀 ························································································ 103
7.1.1 外觀模式 ···················································································· 103
7.1.2 API 外觀····················································································· 104
7.2 API 管理················································································· 105
7.2.1 API 生命週期 ············································································· 106
7.2.2 API 下線····················································································· 107
7.2.3 API 盈利····················································································· 108
第 8 章 API 安全性與快取機制······················································115
8.1 API 安全性-OAuth 2 ······························································ 115
8.1.1 角色···························································································· 116
8.1.2 令牌···························································································· 116
8.1.3 註冊成客戶端············································································· 117
8.1.4 授權授予型別············································································· 118
8.1.5 隱式授予流程············································································· 119
8.1.6 資源擁有者密碼憑據授予 ························································· 121
8.1.7 客戶端憑據授予········································································· 122
8.2 快取機制 ················································································ 123
8.2.1 伺服器快取機制········································································· 124
8.2.2 HTTP 快取機制·········································································· 124
8.2.3 Web 快取機制 ············································································ 126
8.3 小結 ························································································ 129

第 1 章
RESTful API 的基本原理
API 已經不是新興事物了。近幾十年間， API 一直作為介面使得應
用之間可以相互通訊。但 API 的作用在過去幾年中發生了巨大變化。越
來越多的創新型公司發現， 透過為業務夥伴提供 API 介面可利用數字資
產獲利，此外，還可透過為合作伙伴提供更多功能來擴充套件價值主張，以
及透過多種終端和裝置來實現與客戶的連線。建立 API 意味著：允許所
在組織內或組織外的其他人，利用你的服務或產品來建立新應用、吸引
客戶或擴充業務。
其中內部 API 可透過在新應用中最大化重用性和增強一致性， 來提
升開發團隊的生產效率。 公共 API 可透過允許第三方開發人員增強你的
服務或帶來新客戶從而使你的業務增值。一旦開發人員能利用你的服務
和資料開發出新應用，就會形成一種網路效應，從而對底層業務產生顯
著影響。例如， Expedia 透過 API 向合作伙伴開放旅行預訂服務來建立
Expedia 聯盟網路，給公司帶來了新的收入增長點，目前每年能產生 20
億美元的收益。再如， Salesforce 透過釋出 API 使得合作伙伴能夠擴充套件
其平臺的功能，這些基於 SOAP(JAX-WS)以及最近的 RESTful(JAX-RS)
的 API 收益已經貢獻了公司年收入的半壁江山。
最初使用的 SOAP Web 服務依賴許多技術(如 UDDI、 WSDL、 SOAP、
HTTP)和協議，用於在服務提供者和消費者之間傳輸和轉換資料。可使
用 JAX-WS 建立 SOAP Web 服務。
後來， Roy Fielding 於 2000 年發表了他的博士論文 Architectural
Styles and the Design of Network-based Software Architecture 。他創造了
REST 一詞，一種分散式超媒體系統的架構風格。簡而言之， REST(表
述性狀態傳遞， Representational State Transfer 的縮寫)是一種有助於建立
和組織分散式系統的架構風格。這個定義中的關鍵詞應該是“風格”，
因為 REST 很重要的一個方面(也是撰寫本書的一個主要原因)，在於
REST 是一種架構風格，而不是一個準則、一個標準，也不是為最終形
成 RESTful 架構而需要遵循的一系列硬性規則。
本章詳細介紹 REST 基本原理、 SOAP 與 REST 的比較以及 Web 架
構風格。
總之，以 REST 風格組織的分散式系統將在以下幾個方面得到改進：
● 效能： REST 提出的通訊方式是高效簡單的，可在採用它的系統
上實現效能提升；
● 元件互動的可擴充套件性： 任何分散式系統都應能很好地處理這方
面的問題，而 REST 提出的簡單互動極大地滿足了這一點；
● 介面的簡單性：簡單介面允許簡化系統之間的互動，反過來又
可提供上述優點；
● 元件的可變性：系統的分佈性質以及 REST 提出的關注點分離
概念(稍後再次討論)，可使元件以最低成本和風險彼此獨立地
進行修改；
● 可移植性： REST 與技術和語言無關，這意味著可透過任何型別
的技術來實現和使用它(存在一些限制，稍後將談到，但不涉及
具體技術)；
● 可靠性： REST 提出的無狀態(stateless)約束(見稍後的討論)使得
系統在發生故障後更容易恢復；
● 可見性：重述一次， REST 提出的無狀態(stateless)約束增加了所
述請求的完整狀態(稍後會談到這些約束，到時大家就明白了)。
從這個列表中可推斷出 REST 的一些直接優點。以元件為中心
的設計使得系統容錯性非常好。單個元件的故障不影響系統的
整體穩定性，這對於任何系統來說都是一個很大的優點。另外
互連元件是非常容易的，它可最大限度地減少新增新功能或系
統彈性伸縮時的風險。由於 REST 的可移植性(如前所述)，以
REST 為基礎設計的系統將更受大眾的歡迎，具有通用介面的
系統可被更廣泛的開發人員使用。為實現這些屬性和優點，
REST 新增了一組約束以幫助定義統一連線的介面。但如果需
要在客戶端和伺服器之間執行嚴格的互動協議或者執行涉及多
個呼叫的事務，不建議使用 REST。
1.1 SOAP 和 REST 的比較
表 1-1 針對 SOAP 和 REST 各自支援的使用場景進行了全方位比較。
表 1-1 SOAP 和 REST 的比較

主題	SOAP	REST
起源	SOAP(簡單物件訪問協議)是 1998 年由 Dave Winer 等人與微軟合作 時提出的 該協議由大型軟體公司開發，旨在 滿足企業級市場服務需求	REST(表述性狀態傳遞)是由加州 大學爾灣分校的 Roy Fielding 於 2000 年提出的 這個概念誕生於學術環境，涵蓋了 開放式網路的理念
基本 概念	使資料可用作服務(動詞+名詞)， 例 如 getUser 或 PayInvoice	使資料可用作資源(名詞)，例如 user 或 invoice
優點	SOAP 遵循正式的企業規範； 可在任何通訊協議上執行，甚至是 非同步方式； 關於物件的資訊需要傳遞給客戶； 安全性和授權也屬於 SOAP 協議的 一部分； 可使用 WSDL 語言進行完全描述	REST 遵循開放式網路理念； 容易實施和維護； 明確分離客戶端和伺服器的實現； 通訊不由單個實體控制； 客戶端可儲存資訊， 以防多次呼叫； REST 可用多種格式返回資料(如 JSON、 XML 等)
缺點	SOAP 花費大量頻寬來傳遞後設資料； SOAP 實現較困難，在 Web 和移動 應用開發人員中並不受歡迎	REST 僅在 HTTP 協議之上執行； 很難僅在 REST 之上執行授權和安 全性

( 續表)

主題	SOAP	REST
適用 場景	客戶端需要訪問伺服器上可用的 物件； 在客戶端和伺服器之間執行正式 的協議	客戶端和伺服器在 Web 環境中執行； 關於物件 的信 息不需要 傳遞 到客 戶端
不適 用的 場景	如果廣大開發人員希望能夠輕鬆使 用 API， SOAP 不太容易滿足； SOAP 在頻寬非常有限的場景中也 不太適用	需要在客戶端和伺服器之間執行嚴 格的協議時， REST 不適用； 執行涉及多個呼叫的事務時， REST 也不適用
使用 例項	金融服務； 支付閘道器； 電信業務	社交媒體服務； 社交網路； 網路聊天服務； 移動服務
示例	https://www.salesforce.com/developer/ docs/api/-Salesforce SOAP API https://developer.paypal.com/docs/ classic/api/PayPalSOAPAPIArchitect ure/Paypal SOAP API	https://dev.twitter.com/ https://developer.linkedin.com/apis
小結	如果正處理事務性操作，並且已經 有對 SOAP 技術滿意的受眾群體， 可使用 SOAP	如果專注於大規模採用 API 或你的 API 針對移動應用，請使用 REST

1.2 Web 架構風格
根據 Fielding 博士所述，可採用以下兩種方式來定義系統：
● 第一種方式是從一個空白的白板開始。採用這種方式時，直到
系統需求均被滿足時，才能對正在構建的系統有初步瞭解或熟
悉元件的使用；
● 第二種方式是從系統的全套需求開始。為各個元件新增約束，
直至影響系統的各部分能彼此協調地進行互動。
REST 採用第二種方式。為定義 REST 架構，最初會定義一個空狀
態，這個空狀態是一個沒有任何約束條件和元件區分的系統，之後會逐
一對其新增約束條件。下面將介紹 Web 應用架構風格的約束條件。每
個約束條件定義了應如何構建和設計 REST API 框架。當我們向最終用
戶交付 RESTful API 時，另一個需要單獨考慮的方面是安全性。安全性
也是該框架的一部分。
1.2.1 CS 模式
關注點分離是 Web 客戶端-伺服器模式(CS 模式)約束條件的核心主
題。 Web 是基於 CS 模式的系統，客戶端和伺服器在其中發揮著不同的
作用。
只要客戶端和伺服器符合 Web 的統一介面，它們就可以使用任何
語言或技術獨立地實現和部署。
1.2.2 統一資源介面
Web 元件之間的互動依賴它們介面的一致性。 Web 元件包括客戶
端、伺服器和基於網路的中介軟體等。
Web 元件使用統一介面實現一致的互動操作，建立在 Fielding 博士
定義的以下四個約束條件之上：
● 源標識的唯一性：每個資源的資源標識可用來唯一地標明該
資源；
● 資源的自描述性：一個 REST 服務所返回的資源需要能夠描述
自身，並提供用於操作該資源的足夠資訊；
● 訊息的自描述性：每條訊息都包含足夠的資訊來描述如何處理
該訊息；
● 超媒體驅動性(HATEOAS)： 一個典型的 REST 服務不需要額外
的文件來標識透過哪些 URL 訪問特定型別的資源， 而是透過服
務端返回的響應來標識到底能在該資源上執行什麼操作。
1.2.3 分層系統
一般來說，基於網路的中介軟體會為了某些具體目的攔截客戶端和服
務器端之間的通訊，通常用於安全性增強、快取響應和負載平衡等。
分層系統的約束條件使得基於網路的中介軟體(如代理和閘道器)可透過
使用 Web 的統一介面，透明地部署在客戶端和伺服器之間。
1.2.4 快取機制
快取機制是 Web 架構最重要的約束條件之一。快取約束指 Web 服
務器需要具備對每個響應資料的快取能力。
快取響應資料有助於減少客戶端感知的延遲，提高應用的總體可用
性和可靠性，以及控制 Web 伺服器的負載。總之，快取機制降低了 Web
的總體成本。
1.2.5 無狀態
無狀態約束條件規定 Web 伺服器不需要記住其客戶端應用的狀態。
因此，在每次與 Web 伺服器進行互動時，客戶端必須包含其認為與該
次互動相關的所有上下文資訊。
Web 伺服器要求客戶端去管理應用狀態通訊的複雜性，從而使得
Web 伺服器能為更多客戶端提供服務。這種權衡實際上是 Web 架構風
格具有高可擴充套件性的一個關鍵因素。
1.2.6 按需編碼
Web 大量使用按需編碼。按需編碼這一約束條件使得 Web 伺服器
可暫時將可執行程式(如指令碼或外掛)轉移到客戶端。
按需編碼試圖建立 Web 伺服器和客戶端之間的技術耦合，因為客
戶端必須能夠理解並執行從伺服器按需下載的程式碼。出於這個原因，按
需編碼是 Web 架構風格的唯一非必選的約束。
1.2.7 HATEOAS
REST 的最後一條原則是使用超媒體驅動性(Hypermedia As The
Engine Of Applications State， HATEOAS)。當透過使用 HATEOAS 開發
CS 模式的解決方案時，伺服器端的邏輯改變可獨立於客戶端。
超媒體是一種以文件為中心的方法，它支援在文件格式中嵌入其他
服務和資訊的連結。超媒體和超連結的用途之一是將不同來源的資訊合
成複雜的資訊集。這些資訊可來自公司私有云或不同來源的公有云。
例如：
<podcast id="111">
<customer>http://customers.myintranet.com/customers/1
</customers>
<link>
<description> This is my first podcast </description>
</podcast>
每種 Web 架構風格都為 Web 系統增添了有益的特性。透過採用這
些約束條件，開發團隊可建立簡單、可見、可用、可訪問、可演化、
靈活、可維護、可靠、可擴充套件和高效能的系統，如表 1-2 所示。
表 1-2 約束條件和系統特性

約束條件	系統特性
C/S 模式互動	簡單、可演化、可擴充套件
無狀態通訊	簡單、可見、可維護、可演化、可靠
快取資料	可見、可擴充套件、高效能
統一介面	簡單、可用、可見、可訪問、可演化、可靠
分層系統	靈活、可擴充套件、可靠、高效能
按需編碼	可演化

1.3 安全性
本章沒有把安全性作為 REST 基本原理的一部分，但安全性對於交
付 RESTful API 是非常重要的。本書將用完整一章來詳細闡述 RESTful
API 的安全性，包括如何使用 OAuth 協議確保 RESTful API 安全性的最
佳實踐的相關細節， OAuth 目前已成為 RESTful API 安全性的標準。
1.4 什麼是 REST?
前一節簡要介紹了 REST 與 REST API 的基本原理。本節將介紹有
關 REST 概念的更多詳細資訊。
REST 是由 Roy Fielding 博士在博士論文中提出的， 用於描述實現網路
系統的設計模式。 REST 的字面解釋是表述性狀態傳遞(REpresentational
State Transfer)，是一種設計分散式系統的架構風格。它不是一個標準，
而是一組約束條件。它不強行繫結於 HTTP，但通常都與 HTTP 相關聯。
1.4.1 REST 基礎知識
與 SOAP 和 XML-RPC 不同， REST 並不需要新的訊息格式。我們
知道 HTTP API 包括 CRUD(建立、檢索、更新、刪除)等。
● GET =“給我一些資訊” (檢索)；
● POST =“這是一些更新資訊” (更新)；
● PUT =“這是一些新資訊” (建立)；
● DELETE =“刪除一些資訊” (刪除)；
● 還有更多……；
● PATCH = PATCH 方法可用於更新部分資源。例如，當只需要更
新資源的一個欄位時， PUT 完整的資源這種表述可能會很麻煩
而且會佔用更多頻寬；
● HEAD = HEAD 方法與 GET 方法相同，不同之處在於伺服器並
不會在響應中返回訊息體。 HEAD 方法常用於測試超文字連結
的有效性、可訪問性和最近的修改情況；
● OPTIONS = OPTIONS 方法允許客戶端確定與資源相關的選項
或需求，或者伺服器的容量，但這並不意味著資源操作或者初
始化資源檢索；
● “冪等性”概念——當向系統傳送 GET、 DELETE 或 PUT 方法
時，不論該方法傳送多少次，執行效果應該是一樣的，但 POST
方法在集合中建立了實體，因此不是冪等的。
1.4.2 REST 基本原理
據 ProgrammableWeb.com 網站 2016 年的資料，大約有 8356 個 API
是用 REST 寫的。 REST 基於資源架構，資源可透過基於 HTTP 標準方
法的通用介面訪問。 REST 要求開發人員顯式使用 HTTP 方法，並以符
合協議定義的方式使用。每個資源都有一個 URL 標識，且都應該支援
HTTP 的通用操作，同時 REST 允許該資源有不同的表現形式，例如文
本、 XML、 JSON 等。 REST 客戶端可透過 HTTP 協議(內容協商)請求特
定的表現形式。表 1-3 描述了 REST 中使用的資料元素。
表 1-3 REST 結構

資料元素	描述
資源	超文字引用的概念目標，例如 customer/order
資源識別符號	統一資源定位符(URL)或統一資源名稱(URN)標識特定的資源， 例如 http://myrest.com/customer/3435
資源後設資料	描述資源資訊，如標籤、作者、源連結、替代位置、別名
表現形式	資源內容——JSON 訊息、 HTML 文件、 JPEG 圖片
表現後設資料	描述如何處理表現的資訊，如媒介型別、最後修改時間
控制資料	描述如何最佳化響應處理的資訊，例如 if-modified-since、 cache control-expiry

讓我們看一些例子：
1. 資源
首先， GET 播客(podcast)列表的 REST 資源：

其次，獲取 podcast id= 1 的 REST 資源的詳細資訊：
/1
2. 表現形式
以下是透過 id 獲取客戶響應資訊的 XML 表現形式：
RESTful API 開發實戰
10
<Customer
> <id>123</id>
> <name>John</name>
</Customer>
以下是透過 id 獲取客戶響應資訊的 JSON 表現形式：
{"Customer":{"id":"123","name":"John"}}
3. 內容協商
HTTP 天然支援基於 HTTP 協議頭來告知伺服器你所期望的內容
和所能處理的內容。基於此機制， 伺服器將以正確格式返回相應內容，
見圖 1-1。

圖 1-1 內容協商
如果伺服器不支援請求的格式，那麼根據相關規範，伺服器將返回
406 狀態碼(不接受)以通知提出請求的客戶端(即“請求的資源只能根據
請求中包含的 Accept 頭部生成內容，若不能滿足，則返回表示不接受
的狀態碼(406)” )。
1.5 小結
REST 指出了 Web 普及和可擴充套件的關鍵架構原則。 Web 推廣和教
育的下一步工作是將這些原則應用到語義 Web 和 Web 服務領域中。REST
提供了一種簡單、可互操作、靈活的方式來編寫 Web 服務，這種方式
與 WS - *等眾多曾使用的方式迥異。 下一章將更詳細地介紹這些概念。

購買地址：