公開網路服務 / WEB API

要透過以下的 RESTful API 取得資料,只要以一般的 HTTP GET 方法向指定路徑發出 request,即可獲得 純文字/JSON/HTML 型態的文字資料。

本站以 API 提供焦點新聞(news)、主題文庫(archive)、專欄文章(article)的清單與內容,客戶端可能保存前次下載的清單與內容,所以客戶端必須有一個方法能夠知道自己持有的清單與內容是否是最新的:比對版本號碼。

如下表所示,API 對於 news、archive、article 三項內容都提供了 ver 與 list 資料,其中 ver 傳回就單純是一個數字,如果客戶端所持有的數字比它小、就必須以 list 重新下載清單。清單包含了每篇文章的分類、標題、以及 id,然後客戶端可以根據 id 進一步地使用 content 下載該篇文章的 HTML 內容。

API 功能說明 RESTful 路徑 傳回值範例與說明
取得焦點新聞清單版本api/ver/news 以純文字傳回一個數字,代表焦點新聞清單的資料版本,如果客戶端持有的數字與這個數字不同,則表示客戶端的清單資料需要更新。
取得焦點新聞文章清單api/list/news 以 JSON 格式傳回每篇焦點新聞的分類、標題,以及 content id,如以下的例子:
{
   "categories":[
      {
         "name":"禮儀規範",
         "items":[
            {
               "id":"86",
               "title":"詐騙案件數 通訊軟體最大宗",
               "author":"記者梁雅雯╱高雄報導"
               "date":"2014/5/31"
            },
            ...
         ]
      },
      {
         "name":"網路交友",
         "items":[
            ...
         ]
      },
      ...
   ]
}
        
取得主題文庫清單版本api/ver/archives 以純文字傳回一個數字,代表主題文庫清單的資料版本。
取得主題文庫文章清單api/list/archives 以 JSON 格式傳回每篇主題文庫文章的分類、標題,以及 content id。
取得專欄文章清單版本api/ver/articles 以純文字傳回一個數字,代表專欄文章清單的資料版本。
取得專欄文章清單api/list/articles 以 JSON 格式傳回每篇專欄文章的分類、標題,以及 content id。
取得文章內容api/content/id 以 HTML 格式傳回指定 id 的文章內容,其中的 id 數值乃是得自以上的 list API。
搜尋指定標題api/search/str 搜尋焦點新聞、主題文庫、專題文章當中,標題或作者包含指定字串 str 的文章,並且以 JOSN 格式傳回每篇文章的標題,與 content id。

錯誤處理

由於以上的 API 會以 純文字/JSON/HTML 三種格式傳回資料,因此錯誤訊息也以這三種型態呈現,包括沒有內容或搜尋不到文章,如以下例子:

RESTful API 錯誤訊息範例
api/ver/* error: 未知的資料分類
api/list/* 與 api/search/* { "error": "沒有搜尋到任何資料." }
api/content/id <p>沒有這篇文章!</p>

 

版權所有 © 2018 教育部 | 最後更新: 2018/12/14 | 網站瀏覽人數: 3107305