Goto 失敗的回傳值

[RayCHOU]

有 API 的使用者反應以下 URL 呼叫失敗： http://cbdata.dila.edu.tw/v1.2/juans/goto?canon=T&work=2271

查了它的回傳值是這樣：

{
  "num_found": 0,
  "results": [
  ]
}

回傳空值的原因是 T2271 屬於日本撰述部，CBETA 未收錄. 所以也可以說 API 回傳的是正確的.

但是我也在想, 回傳資訊能否更明確？讓使用者知道發生了什麼事。 所以想請問大家有沒有什麼建議？

[jenjouhung]

參考 google 對於JSON API的建議，在error 部份的描述如下： https://google.github.io/styleguide/jsoncstyleguide.xml#error

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
   }
}

所以我會建議，額外建立一個與"results" 相同等級的區塊，內有 code 與 message 說明

[RayCHOU]

參考 google 對於JSON API的建議，在error 部份的描述如下： https://google.github.io/styleguide/jsoncstyleguide.xml#error

感謝介紹，很有參考價值。

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
   }
}

所以我會建議，額外建立一個與"results" 相同等級的區塊，內有 code 與 message 說明

那也許就回傳如下：

{
  "error": {
    "code": 404,
    "message": "Work ID (典籍編號) not found: T2271"
  }
}

Error code 就採用 HTTP Status Code 或是我們要自己規劃、設計一套呢？

[RayCHOU]

以下網址會回傳 error code, message 了： http://cbdata.dila.edu.tw/v1.2/juans/goto?canon=T&work=2271