RESTful API

RESTful API（Representational State Transfer API）是一種基於REST架構風格的應用程式介面設計方法，廣泛用於Web服務和系統之間的資料交換。REST由Roy Fielding在2000年的博士論文中首次提出，強調無狀態性、客戶端-伺服器分離、統一介面、可快取性等原則。RESTful API的核心是通過HTTP協議進行資源的建立、讀取、更新和刪除操作（CRUD）。

RESTful API 的特點

• 無狀態性：每個請求都包含了所有必要的資訊（如身份驗證資訊），伺服器不會在請求之間保留客戶端的狀態。
• 客戶端-伺服器架構：客戶端負責使用者介面和使用者體驗，伺服器負責資料儲存和業務邏輯，二者相互獨立。
• 統一介面：RESTful API使用標準的HTTP動詞（GET、POST、PUT、DELETE等）進行操作，介面設計規範一致，易於理解和使用。
• 可快取性：響應資料可以被標記為可快取，以提高效能和減少伺服器負載。
• 分層系統：通過中間層（如負載均衡器、代理伺服器）提升系統的可伸縮性和安全性。
• 按需編碼：伺服器可以將程式碼或指令碼傳送到客戶端執行，以增強客戶端功能。

HTTP動詞

• GET：用於讀取資源，不會對伺服器上的資源造成任何影響。
• POST：用於建立新資源或提交資料，伺服器處理請求後建立新資源。
• PUT：用於更新現有資源，將客戶端提供的資料覆蓋伺服器上的資源。
• DELETE：用於刪除伺服器上的資源。
• PATCH：用於部分更新資源，改變資源的部分內容。

URL設計

RESTful API使用統一資源識別符號（URI）來表示資源，每個資源有一個唯一的URL。資源之間的關係通過URL層級表示。

示例URL設計：

• GET /books：獲取所有圖書列表。
• GET /books/{id}：獲取特定ID的圖書。
• POST /books：建立新圖書。
• PUT /books/{id}：更新特定ID的圖書。
• DELETE /books/{id}：刪除特定ID的圖書。

響應狀態碼

RESTful API使用HTTP狀態碼來表示請求的處理結果：

• 200 OK：請求成功，返回資料。
• 201 Created：資源建立成功。
• 204 No Content：請求成功，無返回內容。
• 400 Bad Request：請求無效或格式錯誤。
• 401 Unauthorized：請求未經授權。
• 404 Not Found：請求的資源不存在。
• 500 Internal Server Error：伺服器內部錯誤。

示例

以下是一個簡單的RESTful API示例，使用Node.js和Express框架建立一個書籍管理系統。

伺服器程式碼（Node.js + Express）

const express = require("express");
const app = express();
app.use(express.json());

let books = [
  { id: 1, title: "1984", author: "George Orwell" },
  { id: 2, title: "To Kill a Mockingbird", author: "Harper Lee" },
];

// 獲取所有書籍
app.get("/books", (req, res) => {
  res.json(books);
});

// 獲取特定書籍
app.get("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  if (!book) return res.status(404).send("Book not found");
  res.json(book);
});

// 建立新書籍
app.post("/books", (req, res) => {
  const book = {
    id: books.length + 1,
    title: req.body.title,
    author: req.body.author,
  };
  books.push(book);
  res.status(201).json(book);
});

// 更新書籍
app.put("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  if (!book) return res.status(404).send("Book not found");
  book.title = req.body.title;
  book.author = req.body.author;
  res.json(book);
});

// 刪除書籍
app.delete("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === parseInt(req.params.id));
  if (!book) return res.status(404).send("Book not found");
  const index = books.indexOf(book);
  books.splice(index, 1);
  res.status(204).send();
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on port ${port}...`));

總結

RESTful API是一種簡單、靈活、易於擴充套件的Web服務設計方法，通過標準的HTTP協議和動詞進行操作，使得客戶端和伺服器之間的通訊更加直觀和高效。它適用於各種規模的Web應用程式，從小型專案到大型分散式系統。

Clash for Windows 的 RESTful API 實戰

Clash 核心自帶一套 RESTful API（即 external-controller），GUI 介面本身就是通過它驅動的。開啟方式：在配置檔案中設定：

external-controller: 127.0.0.1:9090
secret: "your-secret" # 建議設定，避免本機其他程式任意呼叫

用 curl 操作常見介面（假設控制器地址為 127.0.0.1:9090）：

# 檢視版本
curl http://127.0.0.1:9090/version

# 檢視全部代理與代理組狀態（含延遲快取）
curl -H "Authorization: Bearer your-secret" \
     http://127.0.0.1:9090/proxies

# 檢視單個代理組
curl -H "Authorization: Bearer your-secret" \
     http://127.0.0.1:9090/proxies/%E6%89%8B%E5%8A%A8%E9%80%89%E6%8B%A9

# 切換代理組選中的節點（PUT，body 為節點名）
curl -X PUT -H "Authorization: Bearer your-secret" \
     -H "Content-Type: application/json" \
     -d '{"name":"香港 01"}' \
     http://127.0.0.1:9090/proxies/%E6%89%8B%E5%8A%A8%E9%80%89%E6%8B%A9

# 對一個節點發起延遲測試
curl -H "Authorization: Bearer your-secret" \
     "http://127.0.0.1:9090/proxies/%E9%A6%99%E6%B8%AF%2001/delay?timeout=5000&url=http://www.gstatic.com/generate_204"

# 檢視當前活動連線
curl -H "Authorization: Bearer your-secret" \
     http://127.0.0.1:9090/connections

# 關閉全部連線
curl -X DELETE -H "Authorization: Bearer your-secret" \
     http://127.0.0.1:9090/connections

常用介面速查：

方法	路徑	作用
GET	/version	核心版本
GET	/proxies	全部代理/代理組及狀態
PUT	/proxies/{name}	切換代理組選中節點
GET	/proxies/{name}/delay	單節點延遲測試
GET	/connections	當前活動連線
DELETE	/connections	關閉全部連線
GET/PUT/PATCH	/configs	讀取/過載/修改執行時配置

配合這些介面可以做指令碼化操作，例如定時測速並自動切換節點、在切換節點後自動清理舊連線等。代理組型別的含義見 代理組詳解。