介紹
有趣吧 通過API的方式開放一些應用接口,這篇文檔用來介紹有趣吧目前開放的接口,爲希望開發與有趣吧互通信工具的開發人員提供技術和文檔服務。
概念
認證
除了公共信息(有趣吧網站不需要登錄能夠看到的信息),所有的API方法都需要進行用戶認證, 所有的返回都於認證用戶相關。例如,嘗試獲取一個設置爲私密的且不是您的好友的用戶信息時,將會返回失敗狀態。
有趣吧目前僅支持HTTP Basic Authentication認證協議。當進行Basic Auth,請使用您在有趣吧註冊的郵件地址作爲username部分,記錄在Session或Cookie裏的用戶信息,通過參數傳遞的用戶登錄信息也被支持。
有趣吧的工程師們正在開發同Google's AuthSub or Flickr’s API Authentication相似的認證框架,這對註冊第三方插件應用非常有用,有趣吧開發着論壇將在這些認證框架提供測試時通知大家。
多狀態[RESTFull]結果傳輸
有趣吧 API力求根據用戶的請求返回特定格式的數據,你可以發現我們提供的API中有一個重要的便利之處,通過簡單的更改URI中的文件後綴名,您可以獲得您想要的返回結果的格式,這篇文檔中將說明每個方法中有哪些格式可以用。
有趣吧目前支持以下的四種數據返回格式:XML、JSON、RSS 和Atom,你可以在每次請求時根據請求的方法指定被支持的其中一種結果。
參數
一些API接受可選和必須的參數,當可用時,我們會在接下來的文檔中提到這些參數。注意:當傳送複雜字串時,請一定先將字串編碼爲UTF8格式,並再做一次Url Encode編碼。
HTTP請求
除非特意指明,有趣吧的API開放通過HTTP GET方式的請求,需要提交信息或傳送私密消息的請求應用POST方法。以下將說明,一些API方法將返回基於用戶請求內容相關的信息,而有一些將返回同 客戶端發送的HTTP頭信息相關的一些信息。例如,多數支持since參數的方法,同樣會對HTTP頭中的If-Modified-Since這個Tag 感興趣。需要主意的是,當某些行爲即可以通過參數又可以通過HTTP頭進行控制時,優先接受通過參數方式設定的值。
當請求格式爲XML時,返回數據的編碼爲UTF-8格式,且我們會將一些外部符號編碼爲HTML實體(&#number; 或&text)格式。
HTTP狀態碼
有趣吧API將爲每次請求返回合適的HTTP狀態碼。例如,當請求一個不存在的用戶信息時,我們會返回404 Not Found;當一次請求沒有被認證並授權時,我們會返回401 Not Authorized狀態。
玩轉有趣吧API的簡便方法
如果您的系統安裝有 curl (多數*nix系統應該會有),您已經有了一個非常強大的玩兒有趣吧API的工具。以下是使用curl的例子,非常簡單哦:
- 獲取有趣吧新鮮事:curl http://www.youqubar.com/api/status_json
- 獲取用戶最新發布的趣圖: curl http://www.youqubar.com/api/user_comic_json?id=1
已經公開的API:
status [可用]
獲取有趣吧網站最新的20條新鮮事,該方法不需要身份認證。
訪問地址: http://www.youqubar.com/api/status_[json|xml|rss]
支持格式: xml, json, rss
參數列表:
- count(可選)-記錄數,範圍1-20,默認爲20.
示例:http://www.youqubar.com/api/status_rss?count=10 - callback(可選)-javascript函數名,使用JSON格式時可用,將JSON對象作爲參數直接調用
示例:http://www.youqubar.com/api/status_rss?callback=getStatuses
(現有應用:海內存知己,天涯共有趣;三生萬物,萬物有趣)
user_comic [可用]
獲取有趣吧網站某一個用戶最新發布的趣圖,該方法不需要身份認證。
訪問地址: http://www.youqubar.com/api/user_comic_[json|xml|rss]
支持格式: xml, json, rss
參數列表:
- id(必選)-用戶在有趣吧的id
- count(可選)-記錄數,範圍1-20,默認爲20.
示例:http://www.youqubar.com/api/user_comic_json?id=1&count=2
(現有應用:窗可貼)