為什麼RESTful Web服務設計可以幫你思考正確的事情
我喜愛 RESTful Web 服務或基於 HTTP 的 REST 的原因之一,就是它驅使我思考 API 的重要需求。我也不用花費太多時間來考慮那些無聊的慣例,比如,“我怎麼告訴使用者哪出現問題了?”,相反,我思考,“我怎麼告訴使用者他們的驗證失敗了?”,答:400 狀態碼。完成了。我之後會給出更多的例子,但首先,重要的是要記住,除了 RESTful Web 服務之外,還有更多其他的框架存在。
在我們深入討論可以選擇的框架時,你怎麼知道要選擇哪一個 API 設計框架?做出這決定可能很困難。為了讓事情變的簡單點,Phil Sturgeon 已經ofollow,noindex" target="_blank">提出了一些很好的建議 ,在這裡我會總結一下。其中提到了 3 個流行的框架:RPC/">gRPC, 基於 HTTP 的 REST,以及 GraphQL。他們不是競爭對手,他們有不同的適用範圍。
gRPC 對內部 API 或者與客戶緊密相關的 API 非常適合。
當客戶有非常相似的需求和工作流,還要能執行在不同平臺的時候,基於 HTTP 的 REST 非常適合。
當頻寬有限,而且你不確定客戶需要什麼的時候,GraphQL 更加適用。當你不需要特定伺服器快取和其他類似的協議的時候,它也值得一看。
在進行下一步之前,花點時間對可用資源作一些分析。
一旦你確定基於 HTTP 的 REST 是正確的選擇時,我們看 RESTful Web 服務的一些方面,它們可以讓你深入瞭解優秀的 API 設計。
1. RESTful是資源豐富的
我很欣賞RESTful服務如何迫使我在資源方面進行思考。資源只是API中表示的內容。它不是資料庫表,甚至不必是域模型的實體。它構成了整個API的框架。將你的API視為消費者可以操縱的一組資源。RESTful思維模式鼓勵你思考真正重要的事項。
除此之外,只有一系列有限的方法可以對這些資源起作用:GET、POST、PUT、PATCH和DELETE。它還有一些其他用途,但這些是較大的。這並不意味著你的整個API將變為CRUD(Create, Read, Update, Delete,中譯:增刪改查)。 這意味著在關注其執行的操作之前,你將首先關注系統中的內容。
2.形式高於功能
在採用HTTP服務時,採用已知模式(如JSON模式)也是有益的。基於restful的服務真正打開了一扇門,可以選擇一個健壯的模式規範,它周圍有很多工具。在向消費者展示資料方面,我發現這比我自己的系統要好得多。使用JSON模式這樣的已知資料建模,消費者可以很容易地知道他們要返回的資料的形狀。您還可以讓他們知道是否需要請求欄位。您的消費者甚至可以從中建立驗證器。
3.RestFUL,不是REST
通常情況下,完全REST和使用超媒體並不常見。然而,使用RESTful服務可以幫助我考慮我的消費者將如何使用我的API。即使連結沒有拼寫出來,我也經常從入口點出發,通過連線的資源鏈來理解我的消費者可能如何使用我的API。這可以幫助我找到丟失的資源或沒有意義的資源。
4.RESTful有助於填補這些空白
一旦我有了資源,我發現瀏覽一下主要的方法很有幫助:GET、POST、PUT、PATCH和DELETE。這讓我看到資源是否為只讀的。我可以編輯現有的還是隻建立新的?也許資源足夠大,需要通過補丁進行部分更新。消費者應該能夠移除它嗎?這些是我經常思考的問題。
5.想想那些不幸的道路
我發現檢視HTTP狀態程式碼對了解在資源操作上時會很有用。無法找到資源嗎?我如何知道是消費者犯了錯誤(4xx)而不是伺服器(5xx)?這個資源(409)可能存在併發問題嗎?我把狀態程式碼列表當作一個指南,引發諸如此類的問題,並引導我的思想走向一個健壯的API。
6.告訴世界怎麼停止給你打電話
啊,快取。你知道,當我閱讀HTTP規範時,它讓我大吃一驚,我意識到我們可以在客戶端快取,但讓伺服器告訴我們如何做。現在看來很明顯,但這仍然很強大。在HTTP工作中自然會讓我認識到我的資源有很多可以快取,並讓我專注於如何教消費者快取它們。
你可以花很多時間來確定自己的習慣。您可以為諸如“我如何告訴我的消費者如何快取”或“我如何告訴我的消費者他們犯了錯誤?”或者你可以屈服於老闆的壓力,“把事情做好”。但是如果你真的想要一個好的設計,看看RESTul web服務。如果這個範例符合您的需求,那麼就讓它來引導您的思維,讓它為您的API提供健康的特性。解放你的思想,專注於真正重要的事情。RESTful web服務讓您關注如何使您的API可用且簡單。