文件
API 模型
維持一致 schema 與可預測欄位，降低整合成本。
resource-oriented 設計#
API 以資源為中心命名與分組，讓端點目的清楚、行為可預測。
不同資料主題的差異主要位於 data 內容，而非回應外層框架。
常見頂層欄位#
多數回應會包含 dataset、source_role、freshness、lineage、data。
- dataset：資料主題識別
- source_role：來源角色
- freshness：時效資訊
- lineage：來源追蹤資訊
- data：實際資料內容
data 欄位型態#
data 可能是陣列或單一物件，取決於資源與查詢條件。
建議 parser 先判斷型態，再進入欄位映射，避免固定假設造成解析錯誤。
metadata 與 traceability#
metadata 提供審計與治理所需上下文，應與 data 一起保存。
對於需要重現結果的流程，trace_id、ingested_at 與來源文件識別是關鍵欄位。
錯誤回應格式#
錯誤回應維持固定模型，包含錯誤代碼、訊息與可判斷的處理方向。
建議對 4xx、5xx 分別設計重試與告警策略，不要用同一條重試邏輯。