REST APIs 旨在通過HTTP 的動作語義METHOD, 以替代各種傳統CRUD 操作所帶來的命名問題，例如 "/userAdd"、"/userDelete"、"/userUpdate"、"/userGet"。 REST API 使得你可以僅通過 "/user" + METHOD 替代上述不同的路由。
使用以下提供的資訊以幫助確定何種Method,以應用不同場景：
1.HTTP GET
使用 GET 請求獲取資源資訊 - 且不要以任何方式修改資源，因為 GET 請求不提倡修改資源狀態，由此也被稱為safe methods。
此外，GET APIs 應該是等冪的。 即除非其他的 API （POST or PUT) 修改了伺服器資源狀態，任何時候傳送多次完全相同的 GET 請求應當返回完全相同的資料。
1.1 GET API 響應碼#Response Codes
-
對於任何給定的 HTTP GET API。 如果能在伺服器上找到相應的資源，都必須返回
code 200(ok)-以及 response body. 通常根據平臺實現，返回 xml 或者 json 內容。 -
萬一在伺服器上沒有找到資源，則API 必須返回 HTTP response code 404 (NOT FOUND)
-
如果檢測到 GET 請求本身是錯誤的，伺服器應當返回 HTTP response code 400 (BAD REQUEST)
1.2 示例URIs
HTTP GET http://www/appdomin.com/users
HTTP GET http://www/appdomin.com/users?size=20&page=5
HTTP GET http://www/appdomin.com/users/123
HTTP GET http://www/appdomin.com/users/123/address
2. HTTP POST
POST APIs 用以建立新的子級資源，例如：某個目錄下的子檔案，又或者某個 資料庫表的新增行。
當談及 REST。 POST 方法是用於 給某個集合資源物件 建立一個新的資源
除非 響應包含了適當的 Cache-Control或者 Expires 頭欄位，該METHOD 的想用是不能夠被快取的。
請注意，POST 請求，既不 安全，也不冪等。 並且 呼叫兩次完全相同的 POST 請求將會導致產生包含除了id,其他完全相同資訊的兩個不同的資源。
2.1 POST API Response Codes
-
理想情況下，如果一個資源已經在伺服器上建立過了， 那麼響應應該是： HTTP response code 201(Created), 且包含 1. 描述請求狀態和引用新資源的實體；2.一個 Location 頭。
-
很多時候，POST 方法執行的操作可能返回了一個不能被URI 所標識的資源。 在這種情況下，也應該響應 HTTP response code 200(OK) 或者 204(No Content) 。
2.2 示例 URIs
HTTP POST http://www/appdomin.com/users
HTTP POST http://www/appdomin.com/users/123/accounts
3. HTTP PUT
PUT APIs 主要是用於 更新一個既存的資源(如果這個資源不存在，則該API也可以選擇要不要建立一個新的資源）。
如果這個請求 通過了一個快取， 並且 request-uri 標識了一個或多個當前快取的實體，那麼這些條目應當被視作過時的。 PUT 方法的響應式不可快取的。
3.1 PUT API Response Codes
-
如果已經有一個被 PUT API 建立的新資源， 那麼服務必須返回 HTTP response code 201(Created) 響應。
-
如果一個存在的資源被修改了， 那麼伺服器應該返回 200 (OK) 或者 204 (No Content) 響應狀態碼，以告知請求成功完成。
示例 URIs
HTTP PUT http://www/appdomin.com/users/123
HTTP PUT http://www/appdomin.com/users/123/accounts/456
[POST 和 PUT APIs 的區別(https://restfulapi.net/rest-put-vs-post/) 能夠從請求 URIs 觀察一二： POST 請求是針對資源集合
物件發出的， 而 PUT 請求則是針對單個資源。
4. HTTP DELETE
顧名思義，DELETE APIs 用於刪除資源(由請求 URI 標識)。
DELETE 操作是等冪的，如果你DELETE一個資源，那麼它會從資源集合中移除掉目標
有些人可能認為這使得DELETE方法是非冪等的。這是討論和個人意見的問題。
如果這個請求 通過了一個快取， 並且 request-uri 標識了一個或多個當前快取的實體，那麼這些條目應當被視作過時的。 DELETE 方法的響應式不可快取的
4.1 DELETE API Response Codes
-
如果想用包含了狀態描述的實體#If the response includes an rntity describing the status，一個 DELETE 請求的成功響應，應該是 HTTP response code 200(OK)
-
如果該操作處於等待佇列中，那麼應該返回 202 (Accepted) 。
-
如果操作已經執行，但是響應無實體，那麼返回狀態碼應該是 204 （No Content)。
-
對同個資源重複操作 DELETE API將不會改變輸出 —— 然而， 當對一個 資源執行第二次操作的時候一般會返回 404（NOT FOUND) 應為它已經被刪除掉了。
4.2 示例 URIs
HTTP DELETE http://www.appdomin.com/users/123
HTTP DELETE http://www.appdomain.com/users/123/accouts/456
5. HTTP PATCH
HTTP PATCH 請求被用於對一個資源進行部分更新 #to make a partial update
如果你看到一個PUT 請求也在修改一個資源實體，那麼讓它更加精確 —— PATCH METHOD 就是正確的選擇專用於部分更新一個既存資源。 並且。你應該僅在需要替換某個資源的時候使用 PUT 請求。
請注意，如果你決定在你的應用中使用 PATCH APIs，也有一些挑戰需要注意：
瀏覽器，伺服器，以及web應用框架對PATCH 的支援並不是統一的， IE8，PHP， Tomcat. Django 等等都對 PATCH 不支援或者缺乏支援。
PATCH 請求的 payload#載荷 並不像 PUT 請求那樣簡單，例如：
HTTP GET /user/1
產生如下響應：
{ "id": 1, "username": "admin", "email": "email@example.org" }
一個簡單的PATCH 請求以更新email將會像下面這樣：
HTTP PATCH /users/1
[{ "op": "replace", "path":"/email", "value": "new.email@example.org" }]
根據以下 HTTP 規範，可能會有以下操作：
[
{ "op": "test", "path": "/a/b/c", "value": "foo" },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar"] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/c" },
{ "op": "copy", "from": "/a/b/c", "path": "/a/b/c" },
]
PATCH Method 請不是 POST 或者 PUT Methods 的替代品，它不同於替換整個資源
6. HTTP Methods 總結
下表是上述討論的HTTP methods 的使用總結
The below table summarises the use of HTTP methods discussed above.
| HTTP Method | CRUD | Collection Resource (e.g. /users) | Single Resouce (e.g. /users/123) |
|---|---|---|---|
| POST | Create | 201 (Created), ‘Location’ header with link to /users/{id} containing new ID | Avoid using POST on a single resource |
| GET | Read | 200 (OK), list of users. Use pagination, sorting, and filtering to navigate big lists | 200 (OK), single user. 404 (Not Found), if ID not found or invalid |
| PUT | Update/Replace | 405 (Method not allowed), unless you want to update every resource in the entire collection of resource | 200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid |
| PATCH | Partial Update/Modify | 405 (Method not allowed), unless you want to modify the collection itself | 200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid |
| DELETE | Delete | 405 (Method not allowed), unless you want to delete the whole collection — use with caution | 200 (OK). 404 (Not Found), if ID not found or invalid |
7.相關術語#Glossary
7.1 Safe Methods
如果 Methods 的語義化定義本質上是隻讀的，那麼就被認為 Methods 是安全的。 客戶端不會請求，也不會期望由於對目標資源應用安全方法而導致源伺服器上的任何狀態更改。
GET, HEAD, OPTIONS, TRACE methods 被認為是安全 methods, 就像每個 HTTP 定義的， GET 和 HEAD methods 應該僅被用於資源的獲取，且不會更新/刪除 伺服器上的資源。
區分安全和非安全methods的目的在於，允許自動獲取資源處理（如爬蟲）獲取資料，而不用擔心造成損害。
安全methods 允許使用者代理#agents 其他methods,例如 POST, PUT, DELETE. 以這種獨特的方式，使使用者意識到可能正在要求採取不安全操作的事實 - 他們可以在伺服器上更新/刪除資源，因此應仔細使用。
7.2 Idempotent Methods #冪等方法
如果一次和多次操作所造成的結果均相同，這就是冪等這個詞的含義。
在HTTP 中， PUT, DELETE 以及上述的safy methods (GET, HEAD, OPTIONS, TRACE) 都是冪等操作。
translate @from resuful api