理解 API URL 的設計與 RESTful 概念
更新日期： 2024 年 11 月 18 日
在學習使用 API 時，許多人可能會遇到類似的疑問：
為什麼 API 的不同操作有時候需要使用不同的 URL？是否應該統一使用同一個 URL？
這些疑問，通常源於對 RESTful API 設計的初步接觸，但隨著經驗的累積，理解這些原則可以幫助我們設計更清晰、易維護的 API。
閱讀本文前，建議具備相關概念：
什麼是 API URL？
API URL 是應用程式介面 (Application Programming Interface) 中，用於定位和操作特定資源的網址。
初學者可能會認為每個資源只需一個 URL，對所有操作（如查詢、更新、刪除）都使用這個 URL 即可，並透過 HTTP 方法（GET、POST 等）來區分操作。
實際上，API URL 的設計方式取決於具體的設計風格。
例如，RESTful API 的設計原則提倡資源統一，而有些實作則會採取更直觀的方式，針對每個操作設計不同的 URL。
RESTful API 的設計原則
資源的統一性
在 RESTful API 中，每個資源應該有一個統一的 URL。
例如，對於一組「文章」資源，其 URL 可能是：
- GET
/articles：取得所有文章 - POST
/articles：新增一篇文章 - GET
/articles/{id}：取得特定文章 - PUT
/articles/{id}：更新特定文章 - DELETE
/articles/{id}：刪除特定文章
透過統一的 URL 和不同的 HTTP 方法（GET、POST、PUT、DELETE 等），可以清楚區分操作類型。
清晰的語義
RESTful API 設計強調語義清晰，HTTP 方法本身具有明確的含義：
- GET：讀取資源
- POST：新增資源
- PUT：更新資源
- DELETE：刪除資源
這樣的設計能讓 API 更容易理解與維護。
統一資源標識的優勢
RESTful 的統一設計簡化了 API 結構，讓開發者更容易理解：
- 資源的定位方式統一。
- 操作行為與資源解耦，提升 API 的一致性。
- 更符合 HTTP 協議標準，實現最佳實踐。
實際案例：RESTful 設計 VS 非 RESTful 設計
以一個假設的產品管理 API 為例，我們來比較 RESTful 設計與非 RESTful 設計的不同。
RESTful 設計範例
URL 設計以統一資源標識為核心，並透過 HTTP 方法區分操作：
資源: https://api.example.com/products- GET
/products
用於取得產品清單，例如：
fetch('https://api.example.com/products')
.then(res => res.json())
.then(data => console.log(data));- POST
/products
用於新增一個產品，範例如下：
fetch('https://api.example.com/products', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
title: 'New Product',
price: 100
})
})
.then(res => res.json())
.then(data => console.log(data));- GET
/products/{id}
用於取得特定產品資訊，例如：
fetch('https://api.example.com/products/1')
.then(res => res.json())
.then(data => console.log(data));- PUT
/products/{id}
用於更新特定產品，例如：
fetch('https://api.example.com/products/1', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
title: 'Updated Product',
price: 150
})
})
.then(res => res.json())
.then(data => console.log(data));- DELETE
/products/{id}
用於刪除特定產品，例如：
fetch('https://api.example.com/products/1', {
method: 'DELETE'
})
.then(res => res.json())
.then(data => console.log(data));非 RESTful 設計範例
非 RESTful 設計的 API 常見於以操作為核心，採用不同的 URL 來區分操作：
- GET
/products
用於取得產品清單：
fetch('https://api.example.com/products')
.then(res => res.json())
.then(data => console.log(data));- POST
/products/add
用於新增產品：
fetch('https://api.example.com/products/add', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
title: 'New Product',
price: 100
})
})
.then(res => res.json())
.then(data => console.log(data));- GET
/products/view/{id}
用於查看特定產品資訊：
fetch('https://api.example.com/products/view/1')
.then(res => res.json())
.then(data => console.log(data));- POST
/products/edit/{id}
用於更新產品資訊：
fetch('https://api.example.com/products/edit/1', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
title: 'Updated Product',
price: 150
})
})
.then(res => res.json())
.then(data => console.log(data));- POST
/products/remove/{id}
用於刪除產品：
fetch('https://api.example.com/products/remove/1', {
method: 'POST'
})
.then(res => res.json())
.then(data => console.log(data));RESTful 與非 RESTful 設計的比較
| 設計方式 | 範例 URL | 優點 | 缺點 |
|---|---|---|---|
| RESTful 設計 | /products /products/{id} | 統一資源標識、結構清晰，遵循標準 | 初學者理解成本較高 |
| 非 RESTful 設計 | /products/add /products/edit/{id} | 直觀易懂、初學者友好 | 不符合 RESTful 的一致性原則，可能增加 API 管理的複雜性 |
總結
RESTful API 提倡統一的資源標識，透過 HTTP 方法區分操作，這種設計簡潔、可預測且易於維護。
然而，現實中的 API 設計可能會根據具體需求選擇不同的方式，採取分開 URL 的設計以提升直觀性和初學者的使用體驗。
對於新手而言，建議優先學習 RESTful 設計原則，因為這將幫助你更好地理解 API 的核心邏輯，並能應對不同的設計需求。
