認識 Web API

在前面的任務中，我們學會了如何使用 Django 建立網頁應用程式，透過 Template 來呈現 HTML 頁面給使用者。 但在現代的軟體開發中，很多時候我們需要的不是網頁，而是 API（Application Programming Interface）。

想像一下這些情境：

• 你的網站需要一個手機 App，App 需要從伺服器取得資料
• 你想讓其他開發者能夠存取你的服務（例如 Twitter API、GitHub API）
• 你想用 React、Vue 等前端框架來建立 SPA（Single Page Application）

這些情境下，我們需要的不是 HTML 頁面，而是能夠被程式解析的資料格式（通常是 JSON）。這就是 API 的用途。

開始之前

任務目標

在這個任務中，你將學習：

• 了解什麼是 Web API
• 認識 RESTful API 的設計原則
• 理解 HTTP 方法的用途
• 熟悉常見的 HTTP 狀態碼

什麼是 Web API？

API（Application Programming Interface） 是應用程式之間溝通的介面。 而 Web API 就是透過 HTTP 協定來進行溝通的 API。

當你在瀏覽器中輸入網址時，瀏覽器會向伺服器發送 HTTP 請求，伺服器回傳 HTML 頁面。 Web API 的運作方式類似，但回傳的不是 HTML，而是結構化的資料（通常是 JSON 格式）：

{
    "id": 1,
    "title": "我的第一篇文章",
    "content": "這是文章內容...",
    "is_published": true
}

這種格式讓程式可以輕鬆解析和使用資料，不論是手機 App、前端框架，還是其他後端服務。

RESTful API 設計原則

REST（Representational State Transfer） 是目前最流行的 API 設計風格。 RESTful API 有幾個核心概念：

資源（Resource）

在 REST 中，所有東西都是「資源」。資源可以是：

• 文章（articles）
• 使用者（users）
• 訂單（orders）
• 評論（comments）

每個資源都有一個唯一的 URL 來識別它。

URL 路徑設計

RESTful API 的 URL 設計有一套慣例：

URL 路徑	說明
/api/articles	文章集合（Collection）
/api/articles/1	單一文章（ID 為 1）
/api/articles/1/comments	文章 1 的所有評論（巢狀資源）
/api/articles/1/comments/5	文章 1 的評論 5

設計 URL 時的最佳實踐：

• 使用名詞，不用動詞：用 /articles 而不是 /getArticles
• 使用複數形式：用 /articles 而不是 /article
• 使用小寫字母：用 /articles 而不是 /Articles
• 使用連字號分隔單字：用 /user-profiles 而不是 /userProfiles
• 結尾不加斜線：RESTful API 的慣例是 URL 結尾不加 /

巢狀資源 vs 查詢參數

當資源之間有關聯時，有兩種設計方式：

巢狀資源（適合強關聯）：

GET /api/articles/1/comments      # 取得文章 1 的所有評論
POST /api/articles/1/comments     # 在文章 1 新增評論

查詢參數（適合過濾）：

GET /api/comments?article=1       # 取得文章 1 的所有評論
GET /api/articles?author=5        # 取得作者 5 的所有文章
GET /api/articles?is_published=true&ordering=-created_at

一般來說，如果子資源離開父資源就沒有意義（例如評論一定屬於某篇文章），可以用巢狀資源； 如果只是想過濾資料，用查詢參數更靈活。

HTTP 方法

REST 使用 HTTP 方法來表示對資源的操作，這對應到 CRUD（Create、Read、Update、Delete）：

HTTP 方法	CRUD 操作	說明	範例
GET	Read	取得資源（不會修改資料）	取得文章列表或單一文章
POST	Create	建立新資源	新增一篇文章
PUT	Update	完整更新資源（需提供所有欄位）	更新整篇文章
PATCH	Update	部分更新資源（只提供要修改的欄位）	只更新文章標題
DELETE	Delete	刪除資源	刪除一篇文章

PUT vs PATCH

這兩個方法都用於更新資源，但有重要的差異：

PUT：完整替換資源，需要提供所有欄位

PUT /api/articles/1
{
    "title": "新標題",
    "content": "新內容",
    "is_published": true
}

PATCH：部分更新，只提供要修改的欄位

PATCH /api/articles/1
{
    "title": "只改標題"
}

在實務上，PATCH 更常被使用，因為它更靈活，不需要每次都傳送完整的資料。

完整的 CRUD 範例

以「文章」資源為例：

操作	HTTP 方法	URL	說明
列表	GET	/api/articles	取得所有文章
詳情	GET	/api/articles/1	取得 ID 為 1 的文章
建立	POST	/api/articles	建立新文章
完整更新	PUT	/api/articles/1	完整更新文章 1
部分更新	PATCH	/api/articles/1	部分更新文章 1
刪除	DELETE	/api/articles/1	刪除文章 1

HTTP 狀態碼

HTTP 狀態碼用來告訴客戶端請求的結果。狀態碼分為五大類：

範圍	類別	說明
1xx	Informational	資訊性回應（較少使用）
2xx	Success	請求成功
3xx	Redirection	重新導向
4xx	Client Error	客戶端錯誤（請求有問題）
5xx	Server Error	伺服器錯誤（伺服器出問題）

常見的狀態碼

以下是 API 開發中最常用的狀態碼：

2xx 成功

狀態碼	名稱	說明	常見用途
200	OK	請求成功	GET、PUT、PATCH 成功
201	Created	資源已建立	POST 成功建立新資源
204	No Content	成功但無回傳內容	DELETE 成功

4xx 客戶端錯誤

狀態碼	名稱	說明	常見用途
400	Bad Request	請求格式錯誤	JSON 格式錯誤、驗證失敗
401	Unauthorized	未驗證身分	未登入或 Token 無效
403	Forbidden	沒有權限	已登入但無權存取該資源
404	Not Found	資源不存在	找不到指定的文章
405	Method Not Allowed	不支援此 HTTP 方法	對唯讀資源發送 POST
409	Conflict	資源衝突	重複的唯一值（如 email）
422	Unprocessable Entity	無法處理的實體	資料驗證失敗

5xx 伺服器錯誤

狀態碼	名稱	說明	常見用途
500	Internal Server Error	伺服器內部錯誤	程式 bug、未預期的例外
502	Bad Gateway	閘道錯誤	上游伺服器無回應
503	Service Unavailable	服務暫時無法使用	伺服器維護中

狀態碼使用建議

選擇正確的狀態碼很重要，這裡是一些常見情境的建議：

GET /api/articles
├── 成功 → 200 OK + 文章列表

GET /api/articles/999
├── 成功 → 200 OK + 文章資料
└── 找不到 → 404 Not Found

POST /api/articles
├── 成功 → 201 Created + 新文章資料
├── 驗證失敗 → 400 Bad Request + 錯誤訊息
└── 未登入 → 401 Unauthorized

PUT/PATCH /api/articles/1
├── 成功 → 200 OK + 更新後的資料
├── 找不到 → 404 Not Found
├── 驗證失敗 → 400 Bad Request
└── 沒有權限 → 403 Forbidden

DELETE /api/articles/1
├── 成功 → 204 No Content
├── 找不到 → 404 Not Found
└── 沒有權限 → 403 Forbidden

任務結束

完成！

恭喜你完成了這個任務！現在你已經學會：

• 了解什麼是 Web API
• 認識 RESTful API 的設計原則
• 理解 HTTP 方法的用途
• 熟悉常見的 HTTP 狀態碼

在下一個任務中，我們將學習如何使用 Django REST Framework 來實際建立 RESTful API。