RESTful API 規格參考指南

什麼是 RESTful API?

REST(Representational State Transfer)是一種軟體架構風格,用於設計網路服務。RESTful API 遵循 REST 原則,提供一致且直觀的方式來操作資源。

核心原則核心原則

統一介面(Uniform Interface)
所有資源都通過統一的介面進行操作,使用標準的 HTTP 方法。

無狀態(Stateless)
每個請求都包含處理該請求所需的所有資訊,伺服器不保存客戶端狀態。

可快取(Cacheable)
回應應該明確標示是否可以快取,以提高效能。

分層系統(Layered System)
客戶端無法判斷是直接連接到終端伺服器,還是連接到中間層。

HTTP 方法對應

HTTP 方法用途範例 URL說明
GET讀取資源GET /users獲取所有用戶
GET讀取單一資源GET /users/123獲取 ID 為 123 的用戶
POST創建資源POST /users創建新用戶
PUT完整更新資源PUT /users/123完整更新用戶 123
PATCH部分更新資源PATCH /users/123部分更新用戶 123
DELETE刪除資源DELETE /users/123刪除用戶 123

URL 設計規範

使用名詞,不用動詞

✅ 正確:GET /users
❌ 錯誤:GET /getUsers

使用複數形式

✅ 正確:/users, /products, /orders
❌ 錯誤:/user, /product, /order

階層關係表示

GET /users/123/orders # 獲取用戶 123 的所有訂單
GET /users/123/orders/456 # 獲取用戶 123 的訂單 456

查詢參數用於篩選和分頁

GET /users?page=2&limit=10&status=active
GET /products?category=electronics&sort=price&order=desc

HTTP 狀態碼

成功回應 (2xx)

  • 200 OK – 請求成功
  • 201 Created – 資源創建成功
  • 204 No Content – 請求成功但無回應內容(通常用於 DELETE)

客戶端錯誤 (4xx)

  • 400 Bad Request – 請求語法錯誤
  • 401 Unauthorized – 需要驗證
  • 403 Forbidden – 禁止訪問
  • 404 Not Found – 資源不存在
  • 405 Method Not Allowed – HTTP 方法不被允許
  • 422 Unprocessable Entity – 請求格式正確但語義錯誤

伺服器錯誤 (5xx)

  • 500 Internal Server Error – 伺服器內部錯誤
  • 502 Bad Gateway – 網關錯誤
  • 503 Service Unavailable – 服務暫時無法使用

回應格式規範

成功回應範例

{
    "success": true,
    "data": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "message": "User retrieved successfully"
}

錯誤回應範例

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Email is required",
        "details": {
            "field": "email",
            "value": null
        }
    }
}

列表回應範例

{
    "success": true,
    "data": [
        {"id": 1, "name": "User 1"},
        {"id": 2, "name": "User 2"}
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total": 100,
        "total_pages": 10
    }
}

版本控制

URL 路徑版本控制

GET /v1/users
GET /v2/users

Header 版本控制

GET /users
Accept: application/vnd.api+json;version=1

認證與授權

Bearer Token

Authorization: Bearer your_access_token_here

API Key

X-API-Key: your_api_key_here

最佳實踐

使用 HTTPS
所有 API 端點都應該使用 HTTPS 來確保資料傳輸安全。

提供清楚的錯誤訊息
錯誤回應應該包含足夠的資訊讓開發者理解問題所在。

實作速率限制

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

使用適當的 Content-Type

Content-Type: application/json
Content-Type: application/xml

支援 CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

常見 API 端點範例

# 用戶管理
GET /users # 獲取用戶列表
POST /users # 創建新用戶
GET /users/{id} # 獲取特定用戶
PUT /users/{id} # 更新用戶
DELETE /users/{id} # 刪除用戶

# 文章管理
GET /posts # 獲取文章列表
POST /posts # 創建新文章
GET /posts/{id} # 獲取特定文章
PUT /posts/{id} # 更新文章
DELETE /posts/{id} # 刪除文章

# 巢狀資源
GET /users/{id}/posts # 獲取用戶的文章
POST /users/{id}/posts # 為用戶創建文章
GET /posts/{id}/comments # 獲取文章的評論

四墓庫

辰是春之墓庫
未是夏之墓庫
戌是秋之墓庫
丑是冬之墓庫

四墓庫有很多特性,其中一項特性是「重複現象」。

寅卯月的事情會在辰月重複。
巳午月的事情會在未月重複。
申酉月的事情會在戌月重複。
亥子月的事情會在丑月重複。

1. 墓庫的基本原理

  • 辰為水庫:收藏寅卯木之氣
  • 未為木庫:收藏巳午火之氣
  • 戌為火庫:收藏申酉金之氣
  • 丑為金庫:收藏亥子水之氣

2. 重複現象的深層邏輯

這種重複現象源於五行能量的「蓄積-釋放」循環:
① 當令旺氣(如寅卯木)進入墓庫月時,其能量並未消失,而是被收納儲備
② 在墓庫月中,前個月份的餘氣會再次顯現
③ 這種重複往往表現為相似類型事件的再次發生

3. 具體表現形態

  • 寅卯月事件在辰月重現:可能體現為未完結的文書事務、人際關係的後續發展
  • 巳午月事件在未月重現:常見於財務事項的二次處理、創作項目的返工
  • 申酉月事件在戌月重現:多表現為合同糾紛的再起、競爭關係的反覆
  • 亥子月事件在丑月重現:常涉及隱性問題的暴露、資源分配的再調整

4. 現代應用建議

① 時間管理:在墓庫月預留處理遺留問題的時間
② 決策參考:重要決定宜避開墓庫月的重複效應期
③ 趨勢預判:當某月出現特殊事件時,可預判3個月後可能出現關聯事件

5. 注意事項

重複現象並非簡單複製,而是螺旋式發展的相似事件

  • 具體應驗程度需結合天干透出和八字原局判斷
  • 陽干(甲丙戊庚壬)與陰干(乙丁己辛癸)入墓有差異