RESTful API 設計：URI 範本與回應資料格式解析

開發者詢問 48HoursTopViewPosts/{itemCount} 這類 URI 代表什麼資料格式。本文解析 RESTful API 中 URI 範本設計、HTTP 方法語意與標準回應格式。

URI 解析

GET /48HoursTopViewPosts/{itemCount}

標準回應格式：JSON 是事實標準

現代 REST API 幾乎統一採用 JSON 格式回應：

{
  "data": [
    {
      "postId": 12345,
      "title": "文章標題",
      "viewCount": 9876,
      "author": { "id": 1001, "name": "作者名" },
      "publishedAt": "2024-01-15T10:30:00Z"
    }
    // ... 更多文章物件
  ],
  "meta": {
    "requestedCount": 10,
    "actualCount": 10,
    "timestamp": "2024-01-16T08:00:00Z"
  },
  "links": {
    "self": "/48HoursTopViewPosts/10",
    "next": "/48HoursTopViewPosts/10?offset=10"
  }
}

為什麼是 JSON？

最佳實踐建議

1. 統一回應結構：{ data, meta, links, error } 四大區塊
2. 分頁參數標準化：使用 page/size 或 offset/limit，而非路徑參數傳筆數
3. 錯誤格式標準化：RFC 7807 Problem Details for HTTP APIs
4. 版本控制：URI 前綴 /api/v1/ 或 Header Accept: application/vnd.myapi.v1+json

改良版 URI 設計

GET /api/v1/posts/top-viewed?hours=48&limit=10&offset=0
# 或
GET /api/v1/posts?sort=-viewCount&filter=last48h&limit=10

• 查詢參數比路徑參數更靈活、可選、可組合
• 支援多維度篩選 (排序、時間範圍、分類等)

總結

48HoursTopViewPosts/{itemCount} 是合法的 RESTful URI 範本，語意清晰。回應格式**強烈建議使用 JSON**，並遵循統一結構、標準分頁、版本控制等最佳實踐，打造好用、可維護的 API。