概況
我相信很多人目前在使用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