使用 HTTP 方法進行RESTful服務


概況

我相信很多人目前在使用HTTP請求是大都只會用到GET、POST,GET作為READ讀取數據,POST作為CREATE/UPDTE/DELETE刪除數據,但其實並不僅僅是這樣的,下面小編給大家介紹一下HTTP對應的一些常見謂詞和在restful風格下的使用;

HTTP謂詞是構成了我們“統一接口”約束的主要部分,並為我們提供了與基於名詞的資源相對應的動作。主要最常見的HTTP動詞是(或者正確調用的方法)是POST,GET,PUT,PATCH和DELETE。它們分別對應於create,read,update和delete(或者CURD)操作。還有許多其他動詞,但使用頻率較低。在那些不常用的方法中,OPTIONS和HEAD的使用頻率高於其他的方法。

下面是表總結了主要HTTP方法與資源URI結合使用的建議返回值:

HTTP動詞 CRUD 整個集合 (例如/customers) 特定項目
POST CREATE 201 (Created), 'Location' header with link to /customers/{id} containing new ID. 404 (Not Found), 409 (Conflict) if resource already exists..
GET READ 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. 200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT Update/Replace 405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH Update/Modify 405 (Method Not Allowed), unless you want to modify the collection itself. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE Delete 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. 200 (OK). 404 (Not Found), if ID not found or invalid.

POST

POST動詞最常用於創建**新資源。特別是,它用於創建從屬資源。也就是說,從屬於其他一些(例如父)資源。換句話說,在創建新資源時,對父服務器和服務的POST負責將新資源與父資源相關聯,分配ID(新資源URI)等。

成功創建后,返回HTTP狀態201,返回Location標頭,其中包含指向具有201 HTTP狀態的新創建資源的鏈接。

POST既不安全也不是冪等。因此,建議用於非冪等資源請求。制作兩個相同的POST請求最有可能導致兩個資源包含相同的信息。

例子:

POST http://www.example.com/customers

POST http://www.example.com/customers/12345/orders

GET

HTTP GET方法用於**讀取(或檢索)資源的表示。在“快樂”(或非錯誤)路徑中,GET以XML或JSON格式返回表示形式,並返回HTTP響應代碼200(OK)。在錯誤情況下,它通常返回404(NOT FOUND)或400(BAD REQUEST)。

根據HTTP規范的設計,GET(以及HEAD)請求僅用於讀取數據而不是更改它。因此,當以這種方式使用時,它們被認為是安全的。也就是說,可以調用它們而不存在數據修改或損壞的風險 - 調用它一次具有與調用它10次相同的效果,或者根本沒有。此外,GET(和HEAD)是冪等的,這意味着生成多個相同的請求最終會產生與單個請求相同的結果。

不要通過GET公開不安全的操作 - 它永遠不應該修改服務器上的任何資源。

例子:

GET http://www.example.com/customers/12345

GET http://www.example.com/customers/12345/orders

GET http://www.example.com/buckets/sample

PUT

PUT最常用於更新功能,與已知資源URI一起使用,請求主體包含原始資源的新更新表示。

但是,在客戶端而不是服務器選擇資源ID的情況下,PUT也可用於創建資源。換句話說,如果PUT是包含不存在的資源ID的值的URI。同樣,請求正文包含資源表示。許多人認為這是令人費解和困惑的。因此,如果有的話,應謹慎使用這種創作方法。

或者,使用POST創建新資源並在正文表示中提供客戶端定義的ID - 可能是不包含資源ID的URI(請參閱下面的POST)。

成功更新后,從PUT返回200(如果未返回正文中的任何內容,則返回204)。如果使用PUT進行創建,則在成功創建時返回HTTP狀態201。響應中的主體是可選的 - 提供一個消耗更多帶寬。由於客戶端已經設置了資源ID,因此無需在創建案例中通過Location頭返回鏈接。

PUT不是一個安全的操作,因為它修改(或創建)服務器上的狀態,但它是冪等的。換句話說,如果您使用PUT創建或更新資源,然后再次進行相同的調用,則資源仍然存在,並且仍然具有與第一次調用時相同的狀態。

例如,如果在資源上調用PUT會增加資源中的計數器,則該調用不再是冪等的。有時會發生這種情況,並且可能足以證明呼叫不是冪等的。但是,建議保持PUT請求是冪等的。強烈建議對非冪等請求使用POST。

例子:

PUT http://www.example.com/customers/12345

PUT http://www.example.com/customers/12345/orders/98765

PUT http://www.example.com/buckets/secret_stuff

PATCH

PATCH用於修改功能。PATCH請求只需要包含對資源的更改,而不是完整的資源。

這類似於PUT,但正文包含一組指令,描述如何修改當前駐留在服務器上的資源以生成新版本。這意味着PATCH主體不應該僅僅是資源的修改部分,而是某種補丁語言,如JSON Patch或XML Patch。

PATCH既不安全也不是冪等。然而,PATCH請求可以以冪等方式發布,這也有助於防止在相似時間幀內相同資源上的兩個PATCH請求之間的沖突導致的不良結果。來自多個PATCH請求的沖突可能比PUT沖突更危險,因為某些補丁格式需要從已知的基點操作,否則它們將破壞資源。使用此類補丁應用程序的客戶端應使用條件請求,以便在客戶端上次訪問資源后資源已更新時請求將失敗。例如,客戶端可以在PATCH請求的If-Match標頭中使用強ETag。

例子:

PATCH http://www.example.com/customers/12345

PATCH http://www.example.com/customers/12345/orders/98765

PATCH http://www.example.com/buckets/secret_stuff

DELETE

DELETE很容易理解。它用於**刪除由URI標識的資源。

成功刪除后,返回HTTP狀態200(OK)以及響應正文,可能是已刪除項目的表示(通常需要太多帶寬),或者包裝響應(請參閱下面的返回值)。要么是返回HTTP狀態204(NO CONTENT)而沒有響應正文。換句話說,建議的響應是204狀態,沒有正文,或JSEND樣式響應和HTTP狀態200。

HTTP-spec-wise,DELETE操作是冪等的。如果刪除資源,則會將其刪除。在該資源上反復調用DELETE會導致相同的結果:資源消失了。如果調用DELETE說,遞減計數器(在資源內),則DELETE調用不再是冪等的。如前所述,只要沒有資源數據被更改,就可以更新使用統計和測量,同時仍然考慮服務冪等。建議使用POST進行非冪等資源請求。

但是,有一個關於DELETE idempotence的警告。第二次在資源上調用DELETE通常會返回404(NOT FOUND),因為它已被刪除,因此不再可查找。根據一些觀點,這使得DELETE操作不再是冪等的,但是,資源的最終狀態是相同的。返回404是可以接受的,並准確地傳達呼叫的狀態。

例子:

DELETE http://www.example.com/customers/12345

DELETE http://www.example.com/customers/12345/orders

DELETE http://www.example.com/bucket/sample


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM