寫一下我對restful的理解，最近換工作面試的時候有問到我restful api的東西，工作中以前很多項目也是webapi + js前臺控件的形式構(gòu)建系統(tǒng)。實際上感覺restful太“理想化”,用起來不是特別順手, 舉例說明下：
先看看什么叫restful：
REST的名稱"表現(xiàn)層狀態(tài)轉(zhuǎn)化"中，省略了主語。"表現(xiàn)層"其實指的是"資源"（Resources）的"表現(xiàn)層"。
所謂"資源"，就是網(wǎng)絡(luò)上的一個實體，或者說是網(wǎng)絡(luò)上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務(wù)，總之就是一個具體的實在。你可以用一個URI（統(tǒng)一資源定位符）指向它，每種資源對應(yīng)一個特定的URI。要獲取這個資源，訪問它的URI就可以，因此URI就成了每一個資源的地址或獨一無二的識別符。
客戶端用到的手段，只能是HTTP協(xié)議。具體來說，就是HTTP協(xié)議里面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應(yīng)四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源。
GET /tickets # 獲取ticket列表
GET /tickets/12 # 查看某個具體的ticket
POST /tickets # 新建一個ticket
PUT /tickets/12 # 更新ticket 12.
DELETE /tickets/12 #刪除ticekt 12
實際上呢，不是所有的東西都是“資源”，尤其是在業(yè)務(wù)系統(tǒng)中，缺點如下：
有個接口是更新訂單狀態(tài)，你是用上面的GET POST PUT DELETE 哪個呢，看樣子應(yīng)該是PUT，但是路徑呢PUT /tickets/12
我有時候多個接口 ，更新訂單收款狀態(tài)，更新訂單支款狀態(tài)，更新訂單結(jié)算狀態(tài)；
Restful 的路徑明顯不友好不夠用；
比如，Resuful要求 GET /tickets # 獲取ticket列表 。我們曾經(jīng)有個需求，對方會把不超過1000個訂單id傳給我們，我們系統(tǒng)過濾其中一部分特殊訂單；這也是個查詢服務(wù)，用GET /tickets # 獲取ticket列表的形式，1000個訂單id顯然是超過GET url長度的，這里也不合適；再者，我想開發(fā)多個條件查詢列表服務(wù)，路徑這么淺顯然不合適；
實際業(yè)務(wù)中，我們webapi的路徑是這樣的：systemAlias/controller/action
總結(jié)下規(guī)則：
簡單查詢盡量用GET，好處是可以直接帶查詢參數(shù)copy api路徑；
復(fù)雜查詢和更新用POST，用的最多；
不用PUT和DELETE，原因是增加復(fù)雜度，并沒有帶來什么好處
看看BAT的很多openapi，也是寫著restful，實際沒有嚴格遵守，都是get和post，這是也很多人不知道put和delete的原因
RESTful設(shè)計原則（不同公司具體細節(jié)可能不同）：
在接口命名時應(yīng)該用名詞，不應(yīng)該用動詞，因為通過接口操作到是資源。
在url中加入版本號，利于版本迭代管理更加直觀
https://www.rgc.com/v1/
對于資源的操作類型應(yīng)該是通過http動詞表示。
GET /zoos：列出所有動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的信息
PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物
排序規(guī)則：默認時升序，‘-’為降序;多個排序規(guī)則時以逗號間隔組合。使用sort查詢參數(shù)限制
GET /tickets?sort=-time,created_at
優(yōu)先以time倒序顯示，其次以created_at正序顯示
限制返回值的字段域：明確指定輸出字段列表，用于控制網(wǎng)絡(luò)帶寬和速度。使用fields查詢參數(shù)來限制。
GET /tickets?fileds=id,subject,customer_name,time&sort=-time
返回參數(shù)列表為id,subject,customer_name,time，并且以time字段倒序顯
HTTP Method分別對于資源的CURD操作
GET（SELECT）：從服務(wù)器取出資源（一項或多項）。
POST（CREATE）：在服務(wù)器新建一個資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務(wù)器刪除資源。
保證 POST，PUT，DELETE,PATCH，GET 操作冪等性。
使用SSL(Secure Sockets Layer 安全套接層)
參數(shù)和url采用蛇行命名方式。如：updated_time
服務(wù)器請求和返回的數(shù)據(jù)格式，應(yīng)該盡量使用JSON，避免使用XML。在 request中的Accept和Response中的Content-Type:application/json
restful即表象層狀態(tài)轉(zhuǎn)變。
restful七大原則:
1. C-S架構(gòu)
數(shù)據(jù)的存儲在Server端，Client端只需使用就行。兩端徹底分離的好處使client端代碼的可移植性變強，Server端的拓展性變強。兩端單獨開發(fā)，互不干擾。
2. 無狀態(tài)
http請求本身就是無狀態(tài)的，基于C-S架構(gòu)，客戶端的每一次請求帶有充分的信息能夠讓服務(wù)端識別。
請求所需的一些信息都包含在URL的查詢參數(shù)、header、body，服務(wù)端能夠根據(jù)請求的各種參數(shù)，無需保存客戶端的狀態(tài)，將響應(yīng)正確返回給客戶端。
無狀態(tài)的特征大大提高的服務(wù)端的健壯性和可拓展性。
當然這總無狀態(tài)性的約束也是有缺點的，客戶端的每一次請求都必須帶上相同重復(fù)的信息確定自己的身份和狀態(tài)，造成傳輸數(shù)據(jù)的冗余性，但這種確定對于性能和使用來說，幾乎是忽略不計的。
3.統(tǒng)一的接口
這個才是REST架構(gòu)的核心，統(tǒng)一的接口對于RESTful服務(wù)非常重要?？蛻舳酥恍枰P(guān)注實現(xiàn)接口就可以，接口的可讀性加強，使用人員方便調(diào)用。
4.一致的數(shù)據(jù)格式
服務(wù)端返回的數(shù)據(jù)格式要么是XML，要么是Json，或者直接返回狀態(tài)碼，有興趣的可以看看博客園的開放平臺的操作數(shù)據(jù)的api，post、put、patch都是返回的一個狀態(tài)碼 。
5.系統(tǒng)分層
客戶端通常無法表明自己是直接還是間接與端服務(wù)器進行連接，分層時同樣要考慮安全策略。
6.可緩存
在萬維網(wǎng)上，客戶端可以緩存頁面的響應(yīng)內(nèi)容。因此響應(yīng)都應(yīng)隱式或顯式的定義為可緩存的，若不可緩存則要避免客戶端在多次請求后用舊數(shù)據(jù)或臟數(shù)據(jù)來響應(yīng)。
管理得當?shù)木彺鏁糠值鼗蛲耆爻タ蛻舳撕头?wù)端之間的交互，進一步改善性能和延展性。
7.按需編碼、可定制代碼（可選）
服務(wù)端可選擇臨時給客戶端下發(fā)一些功能代碼讓客戶端來執(zhí)行，從而定制和擴展客戶端的某些功能。
比如服務(wù)端可以返回一些 Javascript 代碼讓客戶端執(zhí)行，去實現(xiàn)某些特定的功能。
grpc和restful的區(qū)別在于它們的通信協(xié)議和數(shù)據(jù)傳輸方式不同。grpc和restful在通信協(xié)議和數(shù)據(jù)傳輸方式上有所區(qū)別。grpc是一種高性能、跨語言的遠程過程調(diào)用（RPC）框架，它使用了二進制的協(xié)議緩沖區(qū)（Protocol Buffers）作為數(shù)據(jù)交換格式，并使用HTTP/2作為底層的傳輸協(xié)議。而restful是一種基于HTTP協(xié)議的軟件架構(gòu)風格，它使用了常見的HTTP方法（GET、POST、PUT、DELETE等）和URL來進行數(shù)據(jù)傳輸。grpc相比于restful具有更高的性能和更小的數(shù)據(jù)傳輸量。由于grpc使用了二進制的協(xié)議緩沖區(qū)，可以更高效地序列化和反序列化數(shù)據(jù)，從而減少了網(wǎng)絡(luò)傳輸?shù)拈_銷。另外，grpc還支持雙向流式傳輸，可以實現(xiàn)更復(fù)雜的通信模式。而restful相對簡單易用，更適合于簡單的數(shù)據(jù)傳輸和對外開放的API接口。因此，在選擇通信協(xié)議和數(shù)據(jù)傳輸方式時，需要根據(jù)具體的需求和場景來進行選擇。
面對對象不同：
RPC 更側(cè)重于動作。
REST 的主體是資源。
RESTful 是面向資源的設(shè)計架構(gòu)，但在系統(tǒng)中有很多對象不能抽象成資源，比如登錄，修改密碼等而 RPC 可以通過動作去操作資源。所以在操作的全面性上 RPC 大于 RESTful。
傳輸效率：
RPC 效率更高。RPC，使用自定義的協(xié)議，對傳輸?shù)臄?shù)據(jù)進行二進制壓縮，可以讓請求報文體積更小，或者使用 HTTP2 協(xié)議，也可以很好的減少報文的體積，提高傳輸效率。
復(fù)雜度：
RPC 實現(xiàn)復(fù)雜，流程繁瑣。
REST 調(diào)用及測試都很方便。
RPC 實現(xiàn)需要實現(xiàn)編碼，序列化，網(wǎng)絡(luò)傳輸?shù)?。?RESTful 不要關(guān)注這些，RESTful 實現(xiàn)更簡單。
靈活性：
HTTP 相對更規(guī)范，更標準，更通用，無論哪種語言都支持 HTTP 協(xié)議。
RPC 可以實現(xiàn)跨語言調(diào)用，但整體靈活性不如 RESTful。
總結(jié)
RPC 主要用于公司內(nèi)部的服務(wù)調(diào)用，性能消耗低，傳輸效率高，實現(xiàn)復(fù)雜。
HTTP 主要用于對外的異構(gòu)環(huán)境，瀏覽器接口調(diào)用，App 接口調(diào)用，第三方接口調(diào)用等
在現(xiàn)代前端開發(fā)中，jQuery是一項不可或缺的工具。它是一個快速、簡潔的JavaScript庫，簡化了文檔的遍歷、事件處理、動畫和Ajax交互。無論您是初學者還是經(jīng)驗豐富的開發(fā)人員，jQuery都為您提供了豐富的功能和便捷的方法來處理各種前端交互。
RESTful架構(gòu)是一種基于網(wǎng)絡(luò)標準HTTP協(xié)議的設(shè)計風格，它廣泛應(yīng)用于現(xiàn)代Web開發(fā)中。通過遵循一組簡潔且統(tǒng)一的原則，RESTful架構(gòu)使得Web應(yīng)用程序更加靈活、可擴展和易于維護。采用RESTful架構(gòu)的Web服務(wù)也更容易實現(xiàn)與其他系統(tǒng)的集成和交互。
將jQuery和RESTful架構(gòu)結(jié)合起來，可以為現(xiàn)代Web應(yīng)用的開發(fā)帶來諸多好處。通過jQuery的強大功能和便捷性，開發(fā)人員可以輕松地實現(xiàn)與后端服務(wù)器的交互和動態(tài)頁面效果。同時，采用RESTful架構(gòu)設(shè)計Web服務(wù)接口，則可以使得應(yīng)用程序更具可擴展性和易維護性。
在現(xiàn)代Web開發(fā)中，通過jQuery來處理RESTful API請求是一種常見且高效的做法。開發(fā)人員可以利用jQuery提供的AJAX方法來發(fā)送GET、POST、PUT和DELETE請求，并處理服務(wù)器返回的數(shù)據(jù)。這種方式使得前端與后端的數(shù)據(jù)交互更加簡單和靈活。
通過jQuery的AJAX方法，開發(fā)人員可以在不刷新整個頁面的情況下，動態(tài)加載數(shù)據(jù)并更新頁面內(nèi)容。這種技術(shù)對于構(gòu)建響應(yīng)式、交互性強的Web應(yīng)用至關(guān)重要。結(jié)合RESTful API設(shè)計，可以構(gòu)建出更加優(yōu)雅和高效的數(shù)據(jù)交互方式。
除了處理數(shù)據(jù)交互，jQuery還提供了豐富的動畫效果和特效，可以優(yōu)化用戶在Web應(yīng)用中的交互體驗。通過使用jQuery的動畫功能，開發(fā)人員可以實現(xiàn)頁面元素的平滑過渡、彈出效果和漸變動畫，為用戶帶來更加流暢和吸引人的界面交互。
綜上所述，jQuery和RESTful架構(gòu)是現(xiàn)代前端開發(fā)中不可或缺的利器。它們?yōu)殚_發(fā)人員提供了豐富的功能和便捷的方式來構(gòu)建現(xiàn)代Web應(yīng)用。通過合理地結(jié)合這兩者，開發(fā)人員可以實現(xiàn)更加高效、優(yōu)雅和具有良好用戶體驗的Web應(yīng)用。
flask restful
在flask基礎(chǔ)上進行一些封裝，主要用于實現(xiàn)restful接口
SOAP(Simple Object Access Protocol)簡單對象訪問協(xié)議，是基于HTTP的一種異構(gòu)系統(tǒng)通信的協(xié)議，說白了就是xml文檔傳輸，之所以會有它，就是在于不同語言C,C++,JAVA等語言開發(fā)的系統(tǒng)進行通信，是WebService就是基于SOAP協(xié)議的，確實是一種比較傳統(tǒng)的SOA解決方案。
REST(Rerepresentational State Transfer)是外國一位博士提出的一種架構(gòu)風格，從資源狀態(tài)轉(zhuǎn)換角度看待資源，但也是基于SOAP協(xié)議進行通信。rest 是一種風格 restful Webservice 和 soap的區(qū)別在于表現(xiàn)形式不一樣，如果想深入了解 可以去開開 深入理解Webservice 這本書，restful Webservice 不只是可以用json 也可以用xml 更可以用html做消息返回， rest 風格的Webservice 和傳統(tǒng)的soap 主要的表現(xiàn)在于 rest是將資源暴露 soap是暴露操作 。
具體的流程其實和soap是一樣的，但是rest更方便，更輕。
在當今互聯(lián)網(wǎng)時代，構(gòu)建高效、可擴展的 Web 應(yīng)用程序是每個開發(fā)人員的必修課程。借助現(xiàn)代技術(shù)，如Spring框架和RESTful API，我們能夠構(gòu)建功能強大且易于維護的應(yīng)用程序。本文將重點探討在Spring框架中如何設(shè)計并實現(xiàn)RESTful JSON API。
RESTful API 是一種基于 REST（Representational State Transfer）架構(gòu)風格設(shè)計的 API。它強調(diào)利用HTTP協(xié)議定義的方法來進行數(shù)據(jù)交互，并使用各種HTTP狀態(tài)碼來表示不同的操作結(jié)果。通過RESTful API，我們可以實現(xiàn)資源的創(chuàng)建、讀取、更新和刪除（CRUD）操作，這使得Web應(yīng)用程序的開發(fā)更加靈活和可靠。
在Spring框架中，我們可以利用Spring MVC模塊來輕松構(gòu)建RESTful API。以下是一些設(shè)計原則，可幫助我們設(shè)計出高質(zhì)量的RESTful API：
JSON（JavaScript Object Notation）是一種輕量級的數(shù)據(jù)交換格式，廣泛應(yīng)用于RESTful API中。它具有易讀性和簡潔性的特點，適合在不同平臺之間進行數(shù)據(jù)傳輸。
在Spring框架中，我們可以借助Jackson庫或Gson庫來實現(xiàn)將Java對象序列化為JSON字符串，并反之。以下是一個簡單的示例：
@RequestMapping(value = "/user", method = RequestMethod.GET)
public ResponseEntity<User> getUser() {
User user = userService.getUser();
return ResponseEntity.ok(user);
}
在上述代碼中，我們通過 `@RequestMapping` 注解定義了一個GET方法的API接口，返回一個User對象。Spring會自動將User對象序列化為JSON格式，并返回給客戶端。
為了提高RESTful API的性能和可維護性，我們還需要考慮一些最佳實踐和性能優(yōu)化策略：
通過本文的學習，我們深入了解了在Spring框架中設(shè)計和實現(xiàn)RESTful JSON API的關(guān)鍵原則和最佳實踐。合理利用RESTful API和JSON數(shù)據(jù)格式，可以幫助我們構(gòu)建出高效、可靠的Web應(yīng)用程序，提升用戶體驗并提高開發(fā)效率。
希望本文能為您在Web應(yīng)用程序開發(fā)中提供一些有用的參考和指導(dǎo)，祝愿您在未來的項目中取得成功！
隨著互聯(lián)網(wǎng)的快速發(fā)展，RESTful API 成為了現(xiàn)代應(yīng)用程序開發(fā)中不可或缺的一部分。PHP 作為一種功能強大的編程語言，為開發(fā)人員提供了許多工具和庫來創(chuàng)建和管理 RESTful API。本文將為您提供關(guān)于如何編寫高質(zhì)量的 PHP RESTful 文檔的詳細指南。
REST（Representational State Transfer）是一種設(shè)計風格，用于構(gòu)建基于網(wǎng)絡(luò)的應(yīng)用程序的架構(gòu)風格。RESTful API 是符合 REST 架構(gòu)風格的 API。它通過使用 HTTP 協(xié)議的不同方法（如 GET、POST、PUT、DELETE 等）來實現(xiàn)對資源的創(chuàng)建、讀取、更新和刪除操作。
RESTful API 的一個關(guān)鍵概念是資源（Resources）。資源是由 URL（統(tǒng)一資源定位符）唯一標識的實體，可以是一個對象、一段文本、一張圖片等。
RESTful API 的文檔是幫助開發(fā)人員理解和使用 API 的關(guān)鍵資源。良好的文檔可以提供清晰的指導(dǎo)，減少潛在的開發(fā)錯誤，并提高整體開發(fā)效率。以下是編寫高質(zhì)量 PHP RESTful API 文檔的幾個重要原則：
下面是編寫 PHP RESTful API 文檔的一些建議和最佳實踐：
為了使文檔具有一致性，您可以使用標準的文檔結(jié)構(gòu)，例如使用 Markdown 或 標記語言。這使得文檔易于閱讀和維護。
在文檔的開頭，提供一些基本信息，比如 API 的名稱、版本信息、作者、許可證等。這些信息可以幫助開發(fā)人員更好地了解 API 的背景和使用情況。
對于每個 API 端點，提供清晰的描述，包括 URL、HTTP 方法、參數(shù)和請求/響應(yīng)示例。使用表格或列表來組織信息，使其易于閱讀和理解。
<h3>List Users</h3>
<p>Get a list of all users.</p>
<strong>URL: /users
<strong>Method: GET
<strong>Parameters:
- limit (optional) - The maximum number of users to return.
- page (optional) - The page number of the results.
<strong>Example Request:
GET /users?limit=10&page=1
<strong>Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"users": [
{"id": 1, "name": "John Doe"},
{"id": 2, "name": "Jane Smith"}
]
}
在文檔中明確說明可能發(fā)生的錯誤以及相應(yīng)的處理方式。列出常見的錯誤代碼和錯誤消息，并提供示例代碼來指導(dǎo)開發(fā)人員如何處理這些錯誤。
示例代碼是幫助開發(fā)人員更好理解使用 API 的重要資源。在文檔中提供可運行的示例代碼，涵蓋常見的編程語言和庫。
包含一個常見問題解答（FAQ）部分，回答開發(fā)人員可能遇到的一些常見問題。這有助于減少對支持團隊的額外負擔，并提供更好的開發(fā)體驗。
編寫高質(zhì)量的 PHP RESTful API 文檔是確保開發(fā)人員能夠輕松理解和使用 API 的關(guān)鍵要素之一。通過遵循本文中的指南和最佳實踐，您可以提供清晰、完整和易于使用的文檔，從而提高整體開發(fā)效率，減少潛在的開發(fā)錯誤。
無論您是 API 提供者還是使用者，正確編寫和使用文檔都是提升開發(fā)過程的重要步驟。因此，我們鼓勵您將此指南作為參考，并根據(jù)自己的需求進行適當?shù)恼{(diào)整。
