「API vs Webhook」比較 介紹 筆記（HTTP RESTful

HTTP：
https://dotblogs.com.tw/jeffyang/2018/04/21/233001
在HTTP協定中，定義了多種不同的method做為服務的請求方法：
GET：取得(想要的服務)的資料或是狀態。（safe & idempotent）
POST：新增一項資料。
PUT：利用更新的方式於"指定位置"新增一項資料。 （idempotent）
PATCH：在現有的資料欄位中，增加或部分更新一筆新的資料。
DELETE：指定資料刪除。 （idempotent）
* idempotent 是指該操作不管做1遍、2遍或多遍，都會得到同樣的資源狀態結果。
* safe 是指該操作不會改變原本的資源狀態，並且同樣的結果是可以被快取（Cache）的。
* POST／PUT 都可以用來新增
- POST的定義上屬於將原先沒有的資料去做一筆新增的動作，
- PUT在定義上(idempotent)無論做多少次，回傳結果都會一樣。
* PATCH／PUT 都可以用來修改
- PATCH則可以針對已經存在的資料欄位去做部分更新
- PUT就像是把整份改好的表格重新上傳。

當Web service使用Web API進行介面介接時
每一串我們設計的URL，就會是一個專屬的服務『窗口』。
簡單說，不同的Method就是對同一件事情做不同的操作。

如果我們在寫一隻商品的WebAPI，大概會長這樣：
獲得商品資料 GET /getAllItems
獲得商品資料 GET /getItem/11
新增商品資料 POST /createItem
更新商品資料 POST /updateItem/
刪除商品資料 POST /deleteItem/



Restful：
https://dotblogs.com.tw/jeffyang/2018/04/21/233001
REST全名 Resource Representational State Transfer
Resource：資源。
Representational：表現形式，如JSON，XML．．．
State Transfer：狀態變化。即上述講到的可利用HTTP動詞們來做呼叫。
將原本五個HTTP的操作對應到資料庫基本操作CRUD。
CRUD 為 Create(新增)、Read(讀取)、Update(更新)與Delete(刪除)的縮寫
PUT 則是比較特別一點，其實它並不直接對應CRUD裡面的任何一項。

相對於前者普通的WebAPI,Restful的形式會長這樣
獲取商品資料 /GET /items
獲取商品資料 /GET /items/1
新增商品資料 /POST /items
更新商品資料 /PATCH /items/1
刪除商品資料 /DELETE /items/1

簡單的說，就是一個單從發出的HTTP要求裡面所包含的資訊
就可以直接預期這要求會收到怎樣類型的資料
充分地使用了 HTTP protocol (GET/POST/PUT/DELETE/PATCH)，達到:
1.以直觀簡潔的資源 URI
2.並且善用 HTTP Verb
3.達到對資源的操作
4.並使用 Web 所接受的資料類型: JSON, XML, YAML 等
Web API沒有一定要照著上面的定義敘述建立
但如果你符合的話，你可以將它稱作Restful API



API：
通常是client端透過api發送request(GET, POST, PUT, PATCH, DELETE)給server端(有一個url)，來要求特定資料，而server端response給clint端，response的內容包含content跟header(status_code= 200)等等，也就是說透過api的話是，client有request server端才有response（request followed by a response），即使client端關心的資料在server上有任何更新，server也不會主動告知，除非client有發request.

以下圖來舉例說明的話：
"data pls?" =
curl -v -X GET -d '{"ID":"1122112", "message":"this is a test."}' -H 'Content-Type:application/json' -H 'Accept:application/json' -H 'Authorization:' https://api.database-server.com/api/data
"nope" =
HTTP/1.1 200 OK
{"ID":"1122112", "gender":"male","change":"nope"}

Webhook：
「Sometimes people call webhooks reverse APIs」但更精準的來說，Webhook比API 省略了一個request的步驟。前面有提到API是「request followed by a response」有問才有答，Webhook則是「it just sends the data when it’s available」「Whenever there’s something new, the webhook will send it to your URL.」主動告知。通常client端需要有一個url提供給server端，server端在有client端關心的訊息發生時，主動透過client端提供的url，發(request)一個POST告知client內容，而client則回傳一個簡單的response ok(status_code= 200)。
以下圖來舉例說明的話：
"data" =
POST -d '{"ID":"1122112", "gender":"female","change":"yes"} -H 'Content-Type:application/json' -H 'Accept:application/json' -H 'Authorization:<token>' https://api.shannon-client.com/receive
"thanks:)" =
HTTP/1.1 200 OK
{"text":"thanks:)"}

https://thenewstack.io/wonderful-world-webhooks/

HTTP response status_code:
https://dotblogs.com.tw/jeffyang/2018/04/21/233001
回應狀態碼是 HTTP 規範的一部分。有相當多的人來處理最常見的情況。本著讓我們的 rest 服務接受 HTTP 規範的精神, 我們的 Web api 應該返回相關的 HTTP 狀態碼。例如, 在成功創建資源 (例如從 POST 請求中) 時, API 應返回 HTTP 狀態碼201。有效的HTTP 狀態碼清單可用此處列出每個的詳細說明。
"前 10" HTTP 回應狀態碼的建議用法如下:
200 OK
常規成功狀態碼。這是最常見的代碼。用來表示成功。
201 CREATED(創建)
成功創建 (通過 POST 或投入)。設置位置標題以包含指向新創建的資源的連結 (開機自檢)。回應正文內容可能存在也可能不存在。
204 NO CONTENT(無內容)
表示成功, 但回應正文中沒有任何東西, 通常用於刪除和放置操作。
400 BAD REQUEST(錯誤請求)
當滿足請求時的常規錯誤將導致無效狀態。域驗證錯誤、缺失資料等是一些例子。
401 UNAUTHORIZED(未經授權)
缺少或不正確身份驗證權杖的錯誤代碼回應。
403 FORBIDDEN(禁止)
當使用者未被授權執行操作或資源因某種原因而無法接通 (例如, 時間限制等) 時的錯誤代碼。
404 NOT FOUND(未找到)
在找不到請求的資源時使用, 無論它是否存在, 或者是否存在401或 403, 出於安全原因, 服務要遮罩。
405 METHOD NOT ALLOWED(方法不允許)
用於指示請求的 URL 存在, 但請求的 HTTP 方法不適用。例如, 發佈users/12345後, API 不支援以這種方式 (提供的 ID) 創建資源。在返回405以指示支援的 HTTP 方法時, 必須設置允許 HTTP 標頭。在前面的情況下, 頁眉看起來像 "允許: 獲取, 放置, 刪除"
409 CONFLICT(衝突)
只要滿足請求, 就會導致資源衝突。重複的條目 (如嘗試創建兩個具有相同資訊的客戶) 不支援串聯刪除時刪除根物件, 這是幾個示例。
500 INTERNAL SERVER ERROR(內部伺服器錯誤)
不要故意把這個還給我。伺服器端引發異常時的常規 catch 錯誤。僅適用于消費者無法從其端位址進行處理的錯誤。