結束第一週 Go 基礎訓練之後，我們就要踏入 Web 的領域了！🎉

這週主要會從 什麼是 API ——> 建立第一支 API 範例 ——> 規劃 To do List API，這三個主要目標來規劃每日的練習。

大家應該很常聽到 API 這個詞吧！在團隊裡面有時候會聽到：
那支 ABC API 是不是壞了啊？ 我送出 request，收到的回應是 500 server error 耶
啊那支 D API 的格式是不是有問題？ …等的情況發生。

那 API 到底是什麼？

API 的全名是 Application Programming Interface，意思是「 應用程式之間的介面 」。

廣泛的來說～大家可以先把它想成，今天如果我要跟一個韓國人說話，但我不會講韓文，對方也不會講中文，於是我們雙方約定好，就使用「英文」講話，英文就是 API。雙方就會依照英文的文法來達成溝通的目的。

所以 API 就是：
👉  建立一個規則，讓雙方可以順利溝通，達成資料交換的目地。

而 Web API 指的就是透過 HTTP 協定 在網路上提供的 API。它可以讓不同系統之間，只要透過網址（URL）和請求方法（GET、POST、PUT/PATCH、DELETE）來交換資料，然後從回應方的那端知道 HTTP 狀態碼 是什麼判斷資料是否請求成功。

所以其實我們每天幾乎都會使用到 API，像是 Google map、智慧家電（IOT）、遊戲 APP 等，這些背後都有呼叫 API 的機制～

那我們就來介紹 API 的幾個元素吧！

1. URL

URL 就是我們請求資源的路徑！

每一支 API 都會有自己的路徑。舉例來說， google map 的網址是這個：https://www.google.com/maps ，當我們在輸入匡輸入 台北101 之後，網址會變成 https://www.google.com/maps/search/台北市101 （實際上還有一些座標位址的資訊，在這邊我們就先忽略），後面的 /search/台北101 就是API 的 URL！

前端送出這個請求路徑之後，後端會根據這個路徑回傳 台北101 的位置相關資料，然後前端再把它顯示在地圖上。如果搜尋別的地點，也是一樣的概念，它一樣以 /search 這個路徑開頭，然後再加上剛剛更換的地點名稱。
所以路徑的命名很重要，它的規劃是需要有邏輯性的。
範例：

• /users ：取得使用者列表。
  • /users/123 ：使用者 ID=123。
  • /users/123/orders ：使用者 123 的訂單。
• /products ：取得產品資料。
  • /products/1 ：ID=1 的產品資料。

從上面的範例來看，URL 的設計需要注意以下幾點：

1. 命名要統一，具一致性。
2. 分層設計要有邏輯。
3. 盡量以名詞為主，避免使用動詞。

2. HTTP Method

是定義 「 要對資源做什麼動作 」 的方法。會搭配 URL 一起，形成完整的請求結構。

常見的方法有：

• GET ：讀取

  • 取得資源、資料。

  • 不會改變伺服器（資料庫）狀態。

  • 範例：

    // 回傳使用者 ID=123 的資訊
    GET /users/123
    

• POST ：建立、新增

  • 新增一個資源、一筆資訊。

  • 會在伺服器（資料庫）建立新的資料。

  • 範例：

    // 新增一筆 Test 使用者資訊
    POST /users
    Body:
    {
      "name": "Test",
      "email": "test@test.com"
    }
    

    回傳：

    {
      "id": 123,
      "name": "Test",
      "email": "test@test.com"
    }
    

• PUT / PATCH ：修改

  • PUT 是 更新/修改 全部；PATCH 是 更新/修改 部分資料。

  • PUT 範例：

    // 把 user 123 改成下面的新資料
    PUT /users/123
    Body:
    {
      "name": "Test 1",
      "email": "test1@test.com"
    }
    

  • PATCH 範例：

    // 只更新 user 123 的 email 資料
    PATCH /users/123
    Body:
    {
      "email": "test1@test.com"
    }
    
    

• DELETE ：刪除

  • 刪除資源。

  • 範例：

    // 刪除 user 123
    DELETE /users/123
    

另外，我們常聽到的 CRUD（Create、Read、Update、Delete）是指資料庫的操作，而 HTTP Methods 很常會跟資料庫來做對應（指 RESTful API 的設計）。所以我們在規劃 API 的時候，也需要把這部分一起考慮進去～

以下是兩者的對應表：

3. Request

客戶端送給伺服器的訊息（就是使用者或是前端送出的請求）。
它告訴伺服器：
👉 我要做什麼（HTTP Methods）、對哪個資源（URL）、還有需要帶什麼資料（Header / Body）。

HTTP Methods 和 URL 在前面已經先介紹過了～這邊會針對 Header、Body 做說明。

• Headers
  • 描述「 請求的額外資訊 」，像是內容類型或是驗證資訊。

    • Content-Type：傳送的資料型別，例如 application/json 。

    • Authorization：帶 Token 或 API Key（身份驗證）。

    • Accept：希望伺服器回傳什麼格式，例如 application/json。（這一個比較不常用）

    • 範例：

      Content-Type: application/json
      Authorization: Bearer <token>
      Accept: application/json        //可省略
      

• Body

  • 當 HTTP Methods 為 POST、PUT、PATCH 時，就會需要帶 Body 資料。

  • 內容通常是 JSON 資料。

  • 範例：

    // 新增使用者 Test
    POST /users 
    Content-Type: application/json
    
    {
      "name": "Test",
      "email": "test@test.com"
    }
    

4. Response

就是回傳給客戶端的回應！
當客戶端（使用者或是前端）發出 Request 給伺服器時，伺服器就會回傳一個 Response。
👉 它會告訴客戶端：請求成功還是失敗？回傳的內容是什麼？

主要的回傳結構會是 Status line + Body。

• Status Line

  • HTTP 版本（例如 HTTP/1.1）。

  • Status Code（狀態碼）：200、404、500...等。

  • Status Text（狀態文字）：OK、Not Found、Internal Server Error。

  • 狀態碼通常會搭配對應的狀態文字，以下是常見的方式：

    // 常用的 HTTP 狀態回傳內容
    
    200 OK： 表示請求成功
    
    400 Bad Request： 請求格式錯誤
    401 Unauthorized： 需要驗證（未登入或 token 無效）
    403 Forbidden： 禁止存取
    404 Not Found： 找不到資源
    
    500 Internal Server Error： 伺服器錯誤
    503 Service Unavailable： 伺服器暫時無法使用
    504 Gateway Timeout： 伺服器回應超時
    

  • 範例：

    // status line 範例
    HTTP/1.1 200 OK
    

• Body

  • 主要要回傳給客戶端的資料。

  • 大部分是 JSON 格式。

  • 範例：

    {
      "id": 123,
      "name": "Test",
      "email": "test1@test.com"
    }
    

所以我們把主要的內容（Status line + Body）合起來，就會得到完整的回應：

HTTP/1.1 200 OK

{
  "id": 123,
  "name": "Test",
  "email": "test1@test.com"
}

以上就是 API 的介紹啦～ 大家明天見！