# HTTP (HyperText Transfer Protocol)

## HTTP 介紹
* 超文本傳輸協議，主要是架構於 [TCP / IP](https://notfalse.net/7/three-way-handshake)之上的<font color="#f00">應用層</font>，為<font color="#f00">無狀態</font>的請求回應通訊協定。
* 常使用在與`Web`瀏覽器和網站服務器之間的傳遞訊息(以明文方式發送內容，不提供任何方式的資料加密)
* 傳輸數據包含:
* `HTML`文件
* 圖片文件
* 查詢結果的超文本格式
* 特性:
* 簡單快速: 客戶向服務器請求服務時，只需傳送請求方法和路徑，由於`HTTP`協議簡單，使得`HTTP`服務器的程序規模小，因而通信速度很快
* 靈活性: `HTTP`允許傳送任意類型的資料種類，傳送類型由`Content-Type`決定
* 無連接: 每次連結只處理一個請求，服務端處理完客戶的請求，並收到客戶的回應後，即斷開連接，以節省傳輸時間
* HTTPS 介紹
* 解決`HTTP`不安全特性 - 為了保證這些隱私資料能加密傳輸，讓`HTTP`運行在安全的[SSL/TLS](https://ithelp.ithome.com.tw/articles/10219106)協議上，即`HTTPS = HTTP + SSL/TSL`通過`SSL`來驗證服務器的身分，並為瀏覽器和服務器之間的通訊進行加密。
* 流程:

## 區別
* HTTP
* `HTTP`協議傳輸是明文，並不安全
* 預設 80 port
* 性能較好
* HTTPS
* `HTTPS`是`HTTP`的安全版本
* `HTTPS`使用`SSL/TSL`協議進行了加密處理，相對安全
* 預設 443 port
* 需設計加密以及多次握手，性能方面不如`HTTP`
* 須取得`SSL`憑證，要錢

## HTTP 冪等性(idempotent)
* `idempotent`是`HTTP`方法的屬性，表示不管執行多少次操作請求，都將產生相同的結果
* `GET`(讀取)：具有冪等性，相同的查詢請求，不管查詢幾次都應該得到相同的結果
* `POST`(新增)：不具冪等性，相同的建立請求，每次執行，都會建立一個新的資料
* `PUT`(修改整份文件)：具冪等性，每次執行更新請求，都是使用同樣的資料覆蓋指定的資料，所以結果不變
* `PATCH`(修改幾個欄位)：不具冪等性。像是有個欄位隨著調用次數在變化的
* `DELETE`(刪除)：具冪等性，刪除資料後，無論重複多少次刪除，也不會改變結果

## HTTP API 版本控制
* 不是所有用戶都會使用最新版本的API，而業務邏輯又是多變的，所以新版本發布時，需要確保向下相容的問題。有以下三種設定方式
* url path: http://api.example.com/v1/resources
* header:
* Accept-Version

            Accept: application/vnd.example.v1+json
            Accept: application/vnd.example+json;version=1.0

* Api-Version: v1
* query parameter: http://api.example.com/resources?version=1
* Media Type Versioning:
* example

            // Request
            GET /resources
            Accept: application/vnd.example-v1+json

            // Response
            HTTP/1.1 200 OK
            Content-Type: application/vnd.example-v1+json
            {
                "data": [
                    { "id": 1, "name": "Resource 1" },
                    { "id": 2, "name": "Resource 2" }
                        ]
            }

            // 當客戶需要使用不同版號的 API 時，可以改變 Accept header 來達成目的
            
            // Request
            GET /resources
            Accept: application/vnd.example-v2+json

            // 當客戶需要使用不同版號的 API 時，可以改變 Accept header 來達成目的
            
            // Response
            HTTP/1.1 200 OK
            Content-Type: application/vnd.example-v2+json
            {
                "data": [
                    { "id": 1, "title": "Resource 1", "description": "Description of Resource 1" },
                    { "id": 2, "title": "Resource 2", "description": "Description of Resource 2" }
                ]
            }

## RESTful API - Richardson成熟模型
* 介紹: 為一個`API`設計指南，提供完整且易於遵循的`API`設計方法。它涵蓋了`API`設計的四個層級
* Level 0: 使用一個`URL`和一個`HTTP`方法，來處理各種請求
* 只使用 [POST] /message，來做到查詢某個訊息、查詢全部訊息、刪除訊息、修改訊息等
* Level 1: 使用多個`URL`和一個`HTTP`方法。各個URL對應要處理的需求
* 使用 [POST] /show_message取得全部訊息、[POST] /create_message新增訊息、[POST] /update_message修改訊息等
* Level 2: 使用多個`URL`和多個`HTTP`方法，並使用`HTTP`回應的`status code`來代表操作結果
* 使用 [GET] /messages取得全部訊息、[POST] /messages新增訊息、[PATCH] /messages/1修改指定訊息等
* HAL
* [連結1](https://en.wikipedia.org/wiki/Hypertext_Application_Language)
* [連結2](https://cloud.tencent.com/developer/article/1675442)
* `API`設定不一定只有`RESTful`或`soap`
* data representation
* 一個`HAL`的回應

              {"_embedded": {
                "messageList": [{
                "text": "msg1",
                "_links": { "self": { "href": "http://localhost:8080/messages/1"}}}]},
                "_links": {
                "self": {"href": "http://localhost:8080/messages"}
                }
              }   

* [HATEOAS](https://zh.wikipedia.org/zh-tw/HATEOAS)
* Level 3: 更進一步的約束`Level 2`，支援`HATEOAS`(Hypermedia As The Engine Of Application State)，類似`HTML`頁面連結，在回傳結果中增加`Hypermedia`(超連結)和動作說明，來代表下一步可以做哪些操作
* 當我們帳戶登入後，可以有存錢、領錢、轉帳、關閉，4種動作

            // Request
            [GET] /account/12345 HTTP/1.1
            Accept: application/xml

            // Response
            HTTP/1.1 200 OK
            Content-Type: application/xml
            <?xml version="1.0"?>
            <account>
            <account_ID>12345</account_ID>
            <link rel="deposit" href="http://xxx/account/12345/deposit" />
            <link rel="withdraw" href="http://xxx/account/12345/withdraw" />
            <link rel="transfer" href="http://xxx/account/12345/transfer" />
            <link rel="close" href="http://xxx/account/12345/close" />
            </account>

### 前端 Level 3 串接

[參考網址1](https://notfalse.net/33/http1_1)
[參考網址2](https://vue3js.cn/interview/http/HTTP_HTTPS.html#%E4%B8%80%E3%80%81http)
[參考網址3](https://www.ithome.com.tw/voice/128528)
[參考網址4](https://hackmd.io/saHgyr0MToW7jyQi4d0FBA)
[Restful API](https://hackmd.io/@monkenWu/Sk9Q5VoV4/https%3A%2F%2Fhackmd.io%2F%40gen6UjQISdy0QDN62cYPYQ%2FHJh9zOE7V?type=book)
[GitHub level 3 restful API 範例](https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28)
資料來源 - NTchMB